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:56:01 +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 值得放進工具箱。

codex-quota 實戰指南：保留命令列的本機、Web 與 Docker 用法

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 後端。
建置失敗顯示找不到檔案：確認執行目錄是專案根目錄，且檔案在建置上下文內。
VS Code 看不到 Docker 資源：重啟 VS Code，並確認 Docker CLI 可用（docker version）。

小結

在 Windows 上用 VS Code 建置 Docker 映像並不困難。先完成 Docker Desktop 與擴充套件安裝，再用命令面板產生 Dockerfile，最後透過 UI 或 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 簡短判斷

相關連結

codex-quota 實戰指南：保留命令列的本機、Web 與 Docker 用法

這個專案做什麼

先準備好帳號憑證

本機 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`