Documenso¶
概述¶
Documenso 係一套開源、可自託管嘅電子簽署平台，用於替代 DocuSign 等商業服務，強調數據自主權同埋可審計性。本機部署採用 Docker Compose 方式，喺 Oracle Cloud Infrastructure（OCI）私有雲環境運行。此實例對應 Documenso Stack，提供數位簽署、文件追蹤、簽署流程管理等功能，適合企業內部合約、授權文件等需要法律效力嘅簽署場合。
架構¶
Documenso 以 Node.js / Next.js 編寫，前後端整合喺同一個容器內。實際部署包含以下組件：
- 應用容器：使用
documenso/documenso:v2.16.0鏡像，容器名稱documenso。容器連接到外部網絡cf_network，並分配固定 IPv4 地址172.21.0.62。此網絡同時連接 Cloudflare Tunnel 同其他服務，讓 Documenso 可以透過內部域名互相訪問。 - 資料庫：共用 PostgreSQL 容器
pg-main，Documenso 使用獨立資料庫名稱documenso。透過NEXT_PRIVATE_DATABASE_URL同NEXT_PRIVATE_DIRECT_DATABASE_URL設定連接字串，用戶名為documenso，密碼由環境變數注入，避免明文儲存。 - 網絡：採用外部 Docker network
cf_network，類型為 bridge。好處係容器之間可以透過容器名或固定 IP 通訊，同時唔暴露主機連接埠，由 Cloudflare Tunnel 負責對外 HTTPS 流量。 - 資源限制：容器設定
mem_limit: 2g、cpus: 2.0，確保唔會耗盡宿主机資源，尤其喺同一主機運行多個容器（如 litellm）時。
部署¶
部署步驟簡述：
- 準備環境：安裝 Docker Engine 同 Docker Compose Plugin，並確保全然網絡
cf_network已建立（docker network create cf_network）。 - 取得鏡像：執行
docker pull documenso/documenso:v2.16.0。 - 設定環境變數：喺
.env檔案定義所有DOCUMENSO_*變數，包括NEXTAUTH_SECRET、ENCRYPTION_KEY、資料庫密碼、SMTP 密碼等。 - 放置簽署憑證：將自簽 p12 檔案放喺
/home/opc/documenso/cert.p12，以唯讀方式掛載入容器/opt/documenso/cert.p12。 - 啟動服務：執行
docker compose up -d，然後用docker compose logs -f檢查啟動日誌。
配置¶
- 公開網址：
NEXT_PUBLIC_WEBAPP_URL設定為https://sign.benhoweb.com，內部網址NEXT_PRIVATE_INTERNAL_WEBAPP_URL則用http://localhost:3000，藉此避免回撥時走外網。 - 資料庫連線：使用 PostgreSQL 字串，指向
pg-main:5432/documenso。因為pg-main喺同一 Docker network，所以直接以服務名解析到容器 IP。 - 電子郵件：透過 Oracle Email Delivery SMTP，設定
NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth，並提供主機、連接埠（通常 587）、帳號同密碼。寄件人名稱設為Documenso，地址由DOCUMENSO_SMTP_FROM_ADDRESS提供。 - 簽署憑證：使用本機 p12 檔案，並設定
NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH=/opt/documenso/cert.p12。為確保簽名喺憑證過期後仍然有效，加入 RFC 3161 時間戳權威http://timestamp.digicert.com。 - 遙測：設定
DOCUMENSO_DISABLE_TELEMETRY=true以停用遙測數據收集，符合企業數據隱私政策。
維運與監控¶
- 健康檢查：容器使用
node -e對http://localhost:3000/發送 fetch，每 30 秒執行一次，容許 90 秒啟動寬限，確保服務真正就緒先至被標記為 healthy。 - 日誌管理：使用
docker logs documenso檢視應用日誌。OCI 層面可以將 Docker logs 導向 OCI Logging，方便集中查詢。 - 更新流程：定期檢查 Documenso 上游發行版本，執行
docker compose pull同docker compose up -d升級。升級前應備份資料庫。 - 備份策略：備份 PostgreSQL 中嘅
documenso資料庫，以及/home/opc/documenso/cert.p12憑證檔案。建議仲要備份.env中嘅機密變數。 - 安全事項：容器固定 IP 令到 Cloudflare Tunnel 可以精準轉發流量，同時避免主機連接埠暴露。另外，
cf_network係外部網絡，與其他服務（例如 litellm）隔離對外，必須透過內部網絡先至可以訪問。
常見問題¶
- 容器無法啟動：檢查環境變數是否齊全，特別係
NEXTAUTH_SECRET同NEXT_PRIVATE_ENCRYPTION_KEY。同時確認cf_network已建立，否則容器會因網絡唔存在而啟動失敗。 - 簽名失敗或證書錯誤：如果 p12 憑證損壞或密碼錯誤，簽署功能會異常。檢查檔案掛載路徑同權限（
ro），並確保證書格式正確。 - 電郵發送唔到：Oracle Email Delivery 可能需要喺雲端控制台設定寄件人驗證。確認
SMTP_PORT（通常 587）同SMTP_HOST正確，並檢查SMTP_FROM_ADDRESS有冇被 SMTP 伺服器拒絕。 - 連線逾時：如果容器訪問
pg-main或 Cloudflare Tunnel 出現 timeout，檢查容器是否喺同一cf_network，以及防火牆規則有無阻擋內部通訊。
相關鏈接¶
- docker – 容器執行環境及 Compose 編排
- litellm – 同網絡下嘅 AI 代理服務
- cloudflare-tunnel – 對外提供 HTTPS 存取嘅通道
- postgres – 共用資料庫服務
- OCI – Oracle Cloud 私有雲架構基礎
來源¶
自動生成（2026-08-19 容器覆蓋率補完第二批）