Docker on KnightLi的博客

用 Docker 部署 Syncthing：Compose、端口和目录映射避坑

Sun, 31 May 2026 12:12:05 +0800

Syncthing 系列目录

在 Docker 中部署 Syncthing 很适合 NAS、家用服务器和 VPS 场景。它可以作为 24 小时在线的同步节点，长期承担照片、文档、Markdown 笔记或下载目录的同步任务。

Docker 部署 Syncthing 的重点不是“能不能跑起来”，而是三个问题：

配置目录要持久化。
需要同步的数据目录要映射到宿主机。
端口和权限要提前处理好。

如果这三点没处理好，容器更新后可能丢配置，Web UI 里填写路径时可能找不到真实目录，或者同步时报 Permission denied。

目录规划

建议先在服务器或 NAS 上准备一个独立目录，例如：

1
2

mkdir -p ~/syncthing
cd ~/syncthing

这个目录里放 docker-compose.yml，并用子目录保存 Syncthing 配置：

1
2
3

syncthing/
├── docker-compose.yml
└── config/

同步数据目录可以放在 NAS 或宿主机已有路径中，例如：

1
2

/volume1/downloads
/volume1/photos

配置目录和数据目录要分开。config 保存 Syncthing 自己的配置、密钥和索引数据库；downloads、photos 这类目录才是你要同步的真实数据。

方案一：Docker Compose

更推荐使用 Docker Compose，后续更新、重启和迁移都更清楚。

在 ~/syncthing/docker-compose.yml 写入：

version: "3"

services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: my-nas-syncthing
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/var/syncthing/config
      - /volume1/downloads:/var/syncthing/downloads
      - /volume1/photos:/var/syncthing/photos
    ports:
      - 8384:8384
      - 22000:22000/tcp
      - 22000:22000/udp
      - 21027:21027/udp
    restart: unless-stopped

启动：

`1`	`docker compose up -d`

查看状态：

1
2

docker compose ps
docker logs -f syncthing

打开 Web UI：

`1`	`http://服务器IP:8384`

首次进入后台后，先设置 GUI 用户名和密码。

方案二：docker run

如果只是快速测试，也可以直接使用 docker run：

docker run -d \
  --name syncthing \
  --hostname my-nas-syncthing \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -p 8384:8384 \
  -p 22000:22000/tcp \
  -p 22000:22000/udp \
  -p 21027:21027/udp \
  -v /path/to/config:/var/syncthing/config \
  -v /path/to/data1:/var/syncthing/data1 \
  --restart unless-stopped \
  syncthing/syncthing:latest

这里的 /path/to/config 和 /path/to/data1 必须换成宿主机真实路径。

例如：

1
2

-v /volume1/docker/syncthing/config:/var/syncthing/config
-v /volume1/photos:/var/syncthing/photos

长期使用时，还是建议改成 Compose 文件，避免每次重建容器都要重新拼命令。

容器内路径和宿主机路径

Docker 新手最容易混淆的是路径。

比如 Compose 里写了：

1
2

volumes:
  - /volume1/photos:/var/syncthing/photos

左边 /volume1/photos 是宿主机路径。右边 /var/syncthing/photos 是容器内路径。

进入 Syncthing Web UI 添加同步文件夹时，文件夹路径必须填写容器内路径：

`1`	`/var/syncthing/photos`

这样 Syncthing 实际操作的才是宿主机上的：

`1`	`/volume1/photos`

如果你在 Web UI 里填 /volume1/photos，容器内部通常并没有这个路径，Syncthing 可能会报错，或者在容器文件系统里创建一个你并不想要的新目录。

配置目录必须持久化

下面这一行很关键：

`1`	`- ./config:/var/syncthing/config`

Syncthing 的配置文件、设备密钥和索引数据库都会放在配置目录里。如果不把它挂载到宿主机，容器删除或重建后，设备 ID 可能变化，原来的设备配对关系也会失效。

建议把配置目录放在稳定路径中，例如：

`1`	`/volume1/docker/syncthing/config`

不要把配置目录放进临时目录，也不要和同步数据目录混在一起。

端口和防火墙

常用端口如下：

8384/TCP   Web UI 管理后台
22000/TCP 设备间同步流量
22000/UDP QUIC 同步流量
21027/UDP 局域网发现

如果 Syncthing 部署在家用 NAS 上，通常要检查：

NAS 自带防火墙是否放行这些端口。
Docker 网桥端口是否正确映射。
路由器是否隔离了 Wi-Fi 和有线网络。
手机和电脑是否在同一网段。

如果部署在云服务器上，还要检查云厂商安全组。尤其是 22000/TCP 和 22000/UDP，如果没有放行，其他设备可能只能通过 relay 连接，速度会明显变慢。

8384 是管理后台端口，不建议直接暴露到公网。如果确实要远程管理，至少要设置强密码，最好再配合反向代理、HTTPS、访问控制或 VPN。

权限问题：PUID 和 PGID

如果启动后 Syncthing 能打开 Web UI，但同步目录时报：

`1`	`Permission denied`

通常是容器进程没有宿主机目录的读写权限。

先在宿主机上查看当前用户的 UID 和 GID：

id

输出类似：

`1`	`uid=1000(user) gid=1000(user) groups=1000(user)`

然后把 Compose 里的环境变量改成对应值：

1
2
3

environment:
  - PUID=1000
  - PGID=1000

同时确认宿主机目录本身允许这个用户读写：

`1`	`ls -ld /volume1/photos`

必要时调整目录所有者或权限：

`1`	`sudo chown -R 1000:1000 /volume1/photos`

在 NAS 系统上不要盲目递归改整个共享目录权限，尤其是多人共享目录。更稳妥的做法是给 Syncthing 单独准备一个同步目录，或者在 NAS 权限管理界面给对应用户授权。

Web UI 首次安全设置

容器启动后，访问：

`1`	`http://服务器IP:8384`

首次进入后台，Syncthing 通常会提示设置 GUI 用户名和密码。这个步骤不要跳过。

建议：

立即设置 GUI 用户名和强密码。
不把 8384 暴露到公网。
远程访问时优先走 VPN、SSH 隧道或受控反向代理。
如果使用反向代理，确认只代理 Web UI，不要误开放其他不必要端口。

如果管理后台被别人控制，对方就可能添加设备、修改共享目录、改变同步关系。Syncthing 的同步数据传输是加密的，但管理入口本身仍然需要保护。

在 Web UI 中添加同步目录

以照片目录为例，Compose 中已经挂载：

`1`	`- /volume1/photos:/var/syncthing/photos`

Web UI 里添加文件夹时：

Folder Label：可以写 Photos。
Folder ID：建议使用稳定英文 ID，例如 photos。
Folder Path：填写 /var/syncthing/photos。
Sharing：选择要共享给哪些设备。
Folder Type：按需求选择 Send & Receive、Send Only 或 Receive Only。

如果这台 Docker 节点是 NAS 中心节点，常见配置是：

普通文档：Send & Receive
手机照片汇总：NAS 上设为 Receive Only
对外分发目录：NAS 上设为 Send Only

具体选择要看你的数据流向。不要所有目录都无脑双向同步。

更新容器

使用 Compose 时，更新通常是：

1
2

docker compose pull
docker compose up -d

只要配置目录和数据目录都正确挂载，更新容器不会丢失设备 ID、配对关系和同步目录配置。

更新前可以先备份配置目录：

`1`	`tar -czf syncthing-config-backup.tar.gz ./config`

配置目录里包含设备私钥，不要把备份文件随便上传到公共位置。

常见问题

Web UI 打不开

先检查容器是否运行：

1
2

docker ps
docker logs syncthing

再检查端口映射：

`1`	`docker port syncthing`

如果容器正常，仍然打不开，检查宿主机防火墙、NAS 防火墙或云服务器安全组。

添加目录后提示不存在

检查你在 Web UI 里填写的是不是容器内路径。

例如宿主机路径是：

`1`	`/volume1/downloads`

容器内路径是：

`1`	`/var/syncthing/downloads`

Web UI 里应该填后者。

只能通过 Relay，速度很慢

优先检查：

22000/TCP 是否放行。
22000/UDP 是否放行。
路由器端口转发是否正确。
云服务器安全组是否同时放行 TCP 和 UDP。
本机防火墙是否拦截 Docker 映射端口。

Relay 能提高可连接性，但不适合长期承担大量同步流量。

同步后文件权限不对

先确认容器运行用户是否正确，再确认宿主机目录权限。Linux、NAS、Windows 共享目录之间的权限模型不同，不要把 Syncthing 当成权限修复工具。

对于跨系统同步，尽量同步普通文件和目录，少同步依赖复杂 ACL、所有者、扩展属性的系统目录。

一个更稳的使用方式

如果你的目标是把 NAS 或服务器作为中心节点，可以这样设计：

NAS 上用 Docker 跑 Syncthing。
配置目录挂载到 /volume1/docker/syncthing/config。
每类数据单独挂载，例如 /volume1/photos、/volume1/notes。
手机、电脑分别添加 NAS 的设备 ID。
重要目录在 NAS 端开启文件版本。
Web UI 只在内网或 VPN 内访问。
NAS 本身再做独立备份，不把同步当作唯一备份。

这样 Syncthing 负责设备间同步，NAS 负责长期在线和版本缓冲，真正的备份再交给快照、外接硬盘或异地备份。

总结

Docker 部署 Syncthing 的关键是把“容器生命周期”和“同步数据生命周期”分开。

容器可以随时更新、重建、迁移；但配置目录和数据目录必须稳定保存在宿主机上。Web UI 里填写的是容器内路径，宿主机权限要通过 PUID、PGID 和目录授权处理，端口要按实际网络环境放行。

只要这几件事配置清楚，Syncthing 很适合作为 NAS、服务器和个人设备之间的轻量同步层。

rembg 项目整理：本地图片背景移除工具

Sun, 19 Apr 2026 08:51:45 +0800

rembg 是一个图片背景移除工具，可以作为命令行工具、Python 库、HTTP 服务或 Docker 容器使用。它的定位很直接：输入一张图，输出带透明通道的前景图，适合产品图、头像、素材批处理和自动化图片处理流程。

这类工具最大的好处是可以本地跑。对于不想把原图上传到在线抠图服务、需要批量处理图片，或者想把背景移除接进脚本和业务系统的人来说，rembg 比网页工具更容易自动化。

01 安装方式

当前版本要求 Python >=3.11,<3.14。安装时需要按硬件选择后端：

`1`	`pip install "rembg[cpu]"`

如果需要命令行工具，加上 cli：

`1`	`pip install "rembg[cpu,cli]"`

NVIDIA CUDA 环境可以安装 GPU 版本：

`1`	`pip install "rembg[gpu,cli]"`

AMD ROCm 环境则需要先按 ROCm 官方方式装好 onnxruntime-rocm，再安装：

`1`	`pip install "rembg[rocm,cli]"`

GPU 版本的坑通常不在 rembg 本身，而在 onnxruntime-gpu、CUDA、cuDNN 和驱动版本是否匹配。装不起来时，先用 CPU 版本确认流程可用，再处理 GPU 环境，会少走很多弯路。

02 CLI 子命令

安装 CLI 后，终端里可以直接使用 rembg。它主要有 4 个子命令：

i：处理单个文件。
p：处理整个文件夹。
s：启动 HTTP 服务。
b：处理 RGB24 像素二进制流，常用于配合 FFmpeg。

查看帮助：

1
2

rembg --help
rembg i --help

处理单张本地图片：

`1`	`rembg i input.png output.png`

从远程图片管道输入：

`1`	`curl -s http://input.png \| rembg i > output.png`

指定模型：

`1`	`rembg i -m u2netp input.png output.png`

只输出 mask：

`1`	`rembg i -om input.png mask.png`

开启 alpha matting：

`1`	`rembg i -a input.png output.png`

-a 对头发、毛边、半透明边缘有时更自然，但速度会慢一些，也不是所有图片都能明显改善。

03 批量处理文件夹

批处理是 rembg 很实用的地方。把原图放到一个目录，输出到另一个目录：

`1`	`rembg p path/to/input path/to/output`

监听目录变化，自动处理新增或修改的图片：

`1`	`rembg p -w path/to/input path/to/output`

这个模式适合和下载脚本、商品图整理、素材文件夹配合使用。比如把待处理图片丢进 input，由 rembg 自动生成透明 PNG 到 output。

04 作为 Python 库调用

如果要接入自己的脚本，最简单的方式是用 remove：

from rembg import remove

with open("input.png", "rb") as i:
    with open("output.png", "wb") as o:
        input_data = i.read()
        output_data = remove(input_data)
        o.write(output_data)

也可以直接处理 PIL 图片：

from rembg import remove
from PIL import Image

input_image = Image.open("input.png")
output_image = remove(input_image)
output_image.save("output.png")

批量处理时建议复用 session，避免每张图片都重新初始化模型：

from pathlib import Path
from rembg import remove, new_session

session = new_session()

for file in Path("input").glob("*.png"):
    output = file.parent / f"{file.stem}.out.png"
    with open(file, "rb") as i:
        with open(output, "wb") as o:
            o.write(remove(i.read(), session=session))

如果你要做一个长期运行的图片处理服务，session 复用比反复调用命令行更合适。

05 启动 HTTP 服务

rembg 也可以直接启动 HTTP 服务：

`1`	`rembg s --host 0.0.0.0 --port 7000 --log_level info`

启动后可以访问：

`1`	`http://localhost:7000/api`

通过 URL 移除背景：

`1`	`curl -s "http://localhost:7000/api/remove?url=http://input.png" -o output.png`

上传本地图片：

`1`	`curl -s -F file=@input.jpg "http://localhost:7000/api/remove" -o output.png`

如果只需要 API，不需要 Gradio UI，可以关闭 UI 以降低空闲 CPU 占用：

`1`	`rembg s --no-ui`

服务模式适合给内网工具、自动化流程或其他应用调用。但它不是完整的图片资产管理系统，鉴权、限流、队列、文件清理这些仍然需要自己在外层补。

06 Docker 运行

CPU 版本可以直接用官方镜像：

`1`	`docker run -v .:/data danielgatis/rembg i /data/input.png /data/output.png`

CUDA 加速需要主机安装 NVIDIA Container Toolkit，并且通常需要自己基于项目里的 Dockerfile_nvidia_cuda_cudnn_gpu 构建镜像：

`1`	`docker build -t rembg-nvidia-cuda-cudnn-gpu -f Dockerfile_nvidia_cuda_cudnn_gpu .`

运行示例：

docker run --rm -it --gpus all \
  -v /dev/dri:/dev/dri \
  -v $PWD:/data \
  rembg-nvidia-cuda-cudnn-gpu \
  i -m birefnet-general /data/input.png /data/output.png

官方 README 提醒，GPU 镜像体积会明显大于 CPU 镜像，而且模型文件不包含在镜像里。为了避免重复下载模型，可以把模型目录挂载出来：

`1`	`docker run -v /path/to/models:/root/.u2net ...`

07 模型选择

rembg 首次使用模型时，会自动下载到 ~/.u2net/。常见模型包括：

u2net：通用模型，适合一般场景。
u2netp：轻量版本，速度和体积更友好。
u2net_human_seg：偏人物分割。
u2net_cloth_seg：偏服装解析。
silueta：类似 u2net，但体积更小。
isnet-general-use：通用场景的新模型。
isnet-anime：偏动漫角色分割。
birefnet-general：README 示例中用于通用图片的模型。
sam：可配合提示点等额外参数使用。

实际使用时，不建议只看模型名字。产品图、人物、二次元图、复杂背景、透明物体，对模型的要求都不一样。比较稳的做法是选一批代表性图片，用几个模型跑一轮，看边缘、漏抠、误抠和速度，再决定默认模型。

如果要使用自定义 .onnx 模型，可以把文件放到默认模型目录 ~/.u2net/，并在需要时设置：

`1`	`MODEL_CHECKSUM_DISABLED=1`

这样可以避免 rembg 因校验逻辑覆盖你放进去的模型文件。

08 适合哪些场景

rembg 很适合这些任务：

批量生成透明背景产品图。
给头像、证件照、素材图做前景提取。
把抠图接入 Python 脚本或后端服务。
在内网部署一个简单的背景移除 API。
用 FFmpeg 管道处理视频帧或序列帧。
对隐私或素材版权敏感，不想上传到第三方在线服务。

它不太适合这些情况：

需要人工级精修边缘和复杂透明材质。
对每张图都要稳定商业摄影级质量。
想要完整在线设计工具，而不是抠图能力。
没有 Python / Docker 环境维护能力。
GPU 驱动、CUDA、ROCm 环境已经很混乱，又急着上线。

09 使用建议

如果只是偶尔处理图片，CPU 版本就够了：

`1`	`pip install "rembg[cpu,cli]"`

如果要批量处理几千张图，优先考虑：

复用 Python session。
固定模型目录，避免重复下载。
用 SSD 存放输入输出和模型文件。
先小批量测试模型效果。
再决定是否折腾 GPU 加速。

GPU 的价值主要在批量吞吐。单张图片偶尔处理时，环境安装成本可能比省下的时间更贵。尤其是 Windows、CUDA、cuDNN、onnxruntime-gpu 版本不匹配时，CPU 版本反而更省心。

10 简短判断

rembg 的优点是简单、开源、形态灵活：命令行能跑，Python 能接，HTTP 能调，Docker 能封装。它很适合做“本地自动抠图”的基础组件。

但它不是魔法橡皮擦。背景复杂、主体边缘细碎、透明材质、阴影保留、商业级精修，都可能需要人工或更专门的流程补充。把它放在批量自动化里时，最好预留人工复检或失败样本回收机制。

如果目标是快速给一批图片去背景，并且希望流程留在本地，rembg 值得放进工具箱。

ChatGPT Codex 配额使用情况查询面板：codex-quota的使用方法

Thu, 16 Apr 2026 18:13:04 +0800

这个项目做什么

codex-quota 是一个轻量工具，能查询 ChatGPT Codex 配额使用情况，数据来源是 https://chatgpt.com/backend-api/wham/usage。

主要功能：

支持单账号或多账号（account/*.auth.json）查询。
输出 five_hour%、weekly%、weekly_reset，并标记来源（network 或 cache）。
对临时失败（408、429、5xx）做指数退避重试。
内置本地缓存，减少已耗尽配额时的重复请求。
提供 Web Dashboard、JSON API、auth 文件管理页面。

优点：

轻量：单脚本可跑，依赖简单。
实用：CLI 和 Web 两种入口都能用。
可部署：支持 Docker 和 Docker Compose。
易运维：支持重试、缓存和定时刷新。

先准备好账号凭证

在 account/<name>.auth.json 创建凭证文件，例如：

{
  "tokens": {
    "access_token": "eyJ...",
    "account_id": "user-xxxxxxxx"
  }
}

解释：

access_token 和 account_id 是查询接口所需字段。
文件名里的 <name> 会作为账号名显示在结果中。

本地 CLI 用法（保留原命令）

安装依赖：

`1`	`pip install -r requirements.txt`

解释：安装项目运行依赖。

查询全部账号：

`1`	`python codex_quota.py`

解释：读取 account/*.auth.json，汇总输出所有账号配额。

查询单个账号：

`1`	`python codex_quota.py your_account_name`

解释：只查询 account/your_account_name.auth.json。

强制刷新（跳过缓存）：

`1`	`python codex_quota.py --refresh`

解释：忽略本地缓存，直接请求最新接口数据。

CLI 参数说明（README 对齐）

account_name：可选账号名（不带 .auth.json）。
--account-dir：凭证目录，默认 account。
--chatgpt-url：配额接口地址。
--raw-json：输出完整 JSON 响应体。
--raw-headers：输出响应头。
--refresh：忽略缓存。
--retries：重试次数，默认 3。
--retry-delay：基础重试间隔秒数，默认 2.0。

Web Dashboard 用法（保留原命令）

启动服务：

`1`	`python codex_quota_service.py --host 0.0.0.0 --port 8081`

解释：启动 HTTP 服务并监听 8081 端口。

访问地址：http://localhost:8081

Service 参数：

--host：监听地址，默认 0.0.0.0。
--port：端口，默认 8081。
--interval-seconds：调度刷新间隔，默认 3600。
--account-dir：凭证目录，默认 account。
--state-file：状态文件路径，默认 <account-dir>/codex_quota_web_results.json。
--account-name：可选，单账号模式。
--chatgpt-url：配额接口地址。
--retries：重试次数。
--retry-delay：基础重试延迟。
--refresh：调度刷新时忽略 CLI 缓存。

HTTP 接口（方便接自动化）

GET /：Dashboard 页面。
GET /api/results：最新结果 JSON。
GET /refresh：立即刷新并跳回 /。
GET /auth：列出 auth 文件。
GET /auth/new：新建 auth 文件表单。
GET /auth/edit?name=<account>：编辑 auth 文件表单。
POST /auth/save：创建/更新 auth 文件。
POST /auth/delete：删除 auth 文件。

Docker 用法（保留原命令）

构建镜像：

`1`	`docker build -t codex-quota .`

解释：把当前项目打包成 codex-quota 镜像。

运行容器（映射 8081）：

`1`	`docker run --rm -p 8081:8081 -v ./account:/app/account codex-quota`

解释：

--rm：容器退出自动删除。
-p 8081:8081：主机端口映射到容器端口。
-v ./account:/app/account：把本地凭证目录挂载进容器。

访问地址：http://localhost:8081

Docker Compose 用法（保留原命令）

启动：

`1`	`docker compose up --build`

解释：按 docker-compose.yml 构建并启动服务。

访问地址：http://localhost:8081

使用建议

多账号场景优先走 Dashboard，便于统一查看和管理 auth 文件。
告警或自动化集成优先用 GET /api/results。
公开仓库不要提交真实 access_token。
如果你看到大量临时错误，可调大 --retries 与 --retry-delay。

Windows 上在 VS Code 里构建 Docker 镜像：从环境准备到一键构建

Thu, 16 Apr 2026 10:20:00 +0800

如果你想在 Windows 上直接用 VS Code 管理并构建 Docker 镜像，流程其实很短。核心就是三步：先把环境装好，再准备 Dockerfile，最后执行构建。

01 前置准备

先确认两项基础条件：

安装并启动 Docker Desktop。
在 VS Code 里安装 Microsoft 官方 Docker 扩展。

在 Windows 上，建议把 Docker Desktop 切到 WSL 2 后端（Settings > Resources > WSL Integration），一般会更稳定、性能也更好。

02 准备 Dockerfile

如果项目里还没有 Dockerfile，可以直接让 VS Code 生成：

在 VS Code 打开你的项目目录。
按 F1 或 Ctrl+Shift+P 打开命令面板。
运行 Docker: Add Docker Files to Workspace。
选择你的平台（例如 Node.js、Python、.NET），按提示完成。

执行后通常会得到至少两个文件：

Dockerfile
.dockerignore

这一步的价值是先有一个可工作的基础版本，后面再按项目需求微调。

03 构建镜像的三种方式

方式 A：右键 Dockerfile

在资源管理器中右键 Dockerfile，选择 Build Image...，然后输入镜像标签（tag）。

方式 B：命令面板

按 F1 运行 Docker: Build Image，再按提示选择上下文和标签。

方式 C：集成终端命令

`1`	`docker build -t your-image-name .`

这条命令表示用当前目录作为构建上下文，生成名为 your-image-name 的镜像。

04 常见问题快速检查

Docker Desktop 没启动：先确认托盘图标显示为运行状态。
构建很慢：优先检查是否启用 WSL 2 后端。
构建失败提示找不到文件：确认执行目录是项目根目录，且 Dockerfile 在上下文内。
扩展看不到 Docker 资源：重启一次 VS Code，或确认 Docker CLI 可用（docker version）。

小结

在 Windows 上用 VS Code 构建 Docker 镜像并不复杂。先安装 Docker Desktop 和 Docker 扩展，再用命令面板生成 Dockerfile，最后用右键或 docker build 即可完成日常构建流程。

RAGFlow 项目整理：开源 RAG 引擎的功能与使用方法

Wed, 15 Apr 2026 22:09:25 +0800

RAGFlow 是 infiniflow 开源的 RAG（Retrieval-Augmented Generation，检索增强生成）引擎。它的目标不是只做一个“上传文件然后问答”的知识库外壳，而是把文档解析、切分、检索、重排、引用溯源、模型配置、Agent 能力和 API 集成放进一套完整工作流里。

如果你正在做企业知识库、文档问答、客服助手、内部资料检索，或者想给 LLM 加一层更可靠的上下文来源，RAGFlow 属于值得重点看的开源方案。

01 RAGFlow 解决什么问题

普通 RAG 系统最容易遇到的问题有三个：

文档解析质量不稳定，尤其是 PDF、扫描件、表格、图片、复杂排版文档。
切分策略不透明，命中结果看起来像“搜到了”，但上下文并不完整。
回答缺少可靠引用，用户很难判断答案来自哪里。

RAGFlow 的重点正好放在这些地方。项目 README 里强调了 Deep document understanding、模板化切分、可视化 chunk、引用溯源和多路召回加重排。换句话说，它更关注“高质量数据进入，高质量答案出来”，而不是只把向量数据库和聊天框接起来。

02 核心功能

1. 深度文档理解

RAGFlow 支持从复杂格式的非结构化数据中抽取知识。README 中列出的数据类型包括 Word、PPT、Excel、TXT、图片、扫描件、结构化数据、网页等。

这对企业知识库很关键。真实资料通常不是干净的 Markdown，而是合同、报告、表格、扫描 PDF、产品手册、截图和网页混在一起。如果解析质量不够，后面的向量检索和 LLM 回答都会被拖垮。

2. 模板化切分

RAGFlow 提供模板化 chunking。它的价值在于：切分策略不是黑盒，可以根据文档类型选择更合适的方式。

例如普通文章、论文、表格、问答文档、图片说明、合同条款，对 chunk 的粒度和边界要求都不一样。模板化切分可以减少“句子被切碎”“表格上下文丢失”“标题和正文分离”这类问题。

3. 可追溯引用

RAGFlow 强调 grounded citations，也就是回答要能追溯到来源片段。它还提供 chunk 可视化，方便人工干预解析和切分结果。

这点对生产环境尤其重要。企业内部问答不是只要“看起来像答案”，还要能查证来源。对于政策、合规、财务、技术文档、客户支持资料来说，引用和溯源几乎是刚需。

4. 自动化 RAG 工作流

RAGFlow 把 RAG 流程做成相对完整的链路：

创建知识库
上传或同步数据
解析文档
查看和干预 chunk
配置 LLM 与 embedding 模型
执行多路召回与重排
构建聊天助手
通过 API 集成到业务系统

这让它更像一个 RAG 平台，而不是一个单点库。对于团队来说，UI、可视化和 API 都有价值：非研发人员可以维护知识库，研发人员可以把能力接入已有系统。

5. Agent、MCP 与工作流能力

RAGFlow 的近期更新里已经包含 Agentic workflow、MCP、Agent Memory、代码执行组件等内容。这说明它不只想做传统知识库问答，也在向 Agent 场景延伸。

典型方向是：Agent 在执行任务时，可以把 RAGFlow 作为可靠的企业知识上下文层；需要查资料时从知识库召回，生成回答时保留引用，必要时再组合工具调用或工作流。

03 基本使用流程

按照官方快速开始文档，RAGFlow 的常见使用路径可以概括为下面几步。

1. 准备运行环境

官方 README 给出的基础要求是：

CPU >= 4 cores
RAM >= 16 GB
Disk >= 50 GB
Docker >= 24.0.0
Docker Compose >= v2.26.1

如果要使用代码执行器的沙箱功能，还需要 gVisor。另外要注意，官方 Docker 镜像主要面向 x86 平台；如果是 ARM64，需要按官方说明自行构建镜像。

2. 拉取项目

1
2

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

3. 检查 `vm.max_map_count`

RAGFlow 部署会依赖 Elasticsearch / OpenSearch 这类组件，因此 Linux 上通常需要确认：

`1`	`sysctl vm.max_map_count`

如果数值低于 262144，可以临时设置：

`1`	`sudo sysctl -w vm.max_map_count=262144`

如果希望重启后仍然生效，需要写入 /etc/sysctl.conf。

4. 使用 Docker Compose 启动

CPU 模式可以直接启动：

`1`	`docker compose -f docker-compose.yml up -d`

如果要用 GPU 加速 DeepDoc 任务，README 中给出的方式是在 .env 中启用 DEVICE=gpu 后再启动：

1
2

sed -i '1i DEVICE=gpu' .env
docker compose -f docker-compose.yml up -d

启动后查看日志：

`1`	`docker logs -f docker-ragflow-cpu-1`

看到服务启动完成后，再通过浏览器访问服务器地址。默认配置下，通常可以直接访问：

`1`	`http://IP_OF_YOUR_MACHINE`

5. 配置模型 API Key

RAGFlow 需要配置 LLM 和 embedding 模型。README 提到可以在 service_conf.yaml.template 中选择默认 LLM factory，并更新对应的 API_KEY。

实际使用时，你需要根据自己的模型供应商配置：

聊天模型
embedding 模型
rerank 模型
多模态模型（如果要理解 PDF / DOCX 中的图片）

6. 创建知识库并上传文档

服务启动后，典型操作是：

登录 Web UI。
创建 dataset / knowledge base。
上传文档或配置数据源同步。
等待解析完成。
查看 chunk 结果，必要时人工调整。
创建聊天助手，选择知识库。
测试问答效果和引用来源。

如果要接入业务系统，可以继续使用 RAGFlow 的 API 或 SDK，把知识库检索和聊天能力接到自己的应用里。

04 适合哪些场景

RAGFlow 适合这些需求：

企业内部知识库问答
产品手册、技术文档、FAQ 检索
客服助手和售前支持助手
合同、报告、制度文件的可追溯问答
多格式资料统一整理
需要 UI 维护知识库，同时又要 API 集成的团队
想把 RAG 能力作为 Agent 上下文层的系统

它尤其适合文档格式复杂、需要引用溯源、希望人工干预解析结果的场景。

05 使用时要注意什么

第一，RAGFlow 不是轻量脚本。它对机器资源有要求，官方建议至少 4 核 CPU、16GB 内存和 50GB 磁盘。如果只是给少量 Markdown 做问答，可能没必要上这么完整的平台。

第二，文档质量仍然重要。RAGFlow 能改善解析和切分，但不能让低质量、过期、互相矛盾的资料自动变得可靠。真正上线前，知识库治理仍然要做。

第三，模型配置会直接影响效果。embedding、rerank、聊天模型、多模态模型的选择，都会影响召回和回答质量。RAGFlow 提供了工作流，但效果仍然要靠数据、模型和参数一起调。

第四，生产环境要关注权限和数据安全。企业知识库里往往有内部资料，部署方式、访问控制、日志、API Key、模型供应商数据策略都要提前设计。

06 简短判断

RAGFlow 的优势在于把 RAG 里最麻烦的部分做成了平台化能力：复杂文档解析、可解释切分、引用溯源、多路召回、重排、模型配置、Web UI、API 和 Agent 扩展。

如果你要做的是可验证、可维护、可接入业务系统的企业知识库，RAGFlow 比“向量库 + 简单聊天 UI”的方案更完整。反过来，如果只是个人小规模资料问答，或者数据格式非常简单，轻量 RAG 框架可能更省资源。

Docker on KnightLi的博客

用 Docker 部署 Syncthing：Compose、端口和目录映射避坑

Syncthing 系列目录

目录规划

方案一：Docker Compose

方案二：docker run

容器内路径和宿主机路径

配置目录必须持久化

端口和防火墙

权限问题：PUID 和 PGID

Web UI 首次安全设置

在 Web UI 中添加同步目录

更新容器

常见问题

Web UI 打不开

添加目录后提示不存在

只能通过 Relay，速度很慢

同步后文件权限不对

一个更稳的使用方式

总结

rembg 项目整理：本地图片背景移除工具

01 安装方式

02 CLI 子命令

03 批量处理文件夹

04 作为 Python 库调用

05 启动 HTTP 服务

06 Docker 运行

07 模型选择

08 适合哪些场景

09 使用建议

10 简短判断

相关链接

ChatGPT Codex 配额使用情况查询面板：codex-quota的使用方法

这个项目做什么

先准备好账号凭证

本地 CLI 用法（保留原命令）

CLI 参数说明（README 对齐）

Web Dashboard 用法（保留原命令）

HTTP 接口（方便接自动化）

Docker 用法（保留原命令）

Docker Compose 用法（保留原命令）

使用建议

Windows 上在 VS Code 里构建 Docker 镜像：从环境准备到一键构建

01 前置准备

02 准备 Dockerfile

03 构建镜像的三种方式

方式 A：右键 Dockerfile

方式 B：命令面板

方式 C：集成终端命令

04 常见问题快速检查

小结

RAGFlow 项目整理：开源 RAG 引擎的功能与使用方法

01 RAGFlow 解决什么问题

02 核心功能

1. 深度文档理解

2. 模板化切分

3. 可追溯引用

4. 自动化 RAG 工作流

5. Agent、MCP 与工作流能力

03 基本使用流程

1. 准备运行环境

2. 拉取项目

3. 检查 vm.max_map_count

4. 使用 Docker Compose 启动

5. 配置模型 API Key

6. 创建知识库并上传文档

04 适合哪些场景

05 使用时要注意什么

06 简短判断

相关链接

3. 检查 `vm.max_map_count`