↑ 需求首頁 ⌂ 需求中心

FR-130.1 探脈報告——SeaweedFS／Redis 走 TLS 的實測與連線點清單

卡片：CM-2498（母卡 CM-2497）。只讀不寫程式碼。 實測環境：本機 docker（chrislusf/seaweedfs:3.99、redis:7-alpine），自簽 CA 照安裝器同款參數（pathlen:0），終端憑證 SAN＝DNS:guidant-<服務>,DNS:localhost,IP:127.0.0.1；Python 端用 BE .venv（minio 7.2.20、urllib3 2.8.0、redis 5.2.1、Flask-SocketIO 5.6.1、python-socketio 5.16.4、eventlet 0.40.4）。未碰任何遠端環境。

§1

一句話結論

四件印象中三件對、一件要補：參數名、minio 吃 CA 的方式、eventlet＋rediss 都可行；但有三個「不改會靜默壞掉」的陷阱（SSL_CERT_FILE 會整份取代公開 CA、redis-py 預設不驗 hostname、SocketIO 缺 CA 時服務照起但推播永遠收不到），以及一個母卡沒列到的缺口——SeaweedFS 的 filer 8888 在 docker 內網是明文、免帳密可直接讀檔，只把 S3 加密等於沒關門。

§2

A. SeaweedFS 3.99 的 S3 TLS

查了什麼：docker run chrislusf/seaweedfs:3.99 server -h，再起一顆帶自簽憑證的實連。

看到什麼

  • 旗標（server 模式，前綴 -s3.）：
    • -s3.cert.file、-s3.key.file——首腦印象正確。
    • -s3.cacert.file＋-s3.tlsVerifyClientCert——要求 client 憑證用（mTLS），本 FR 不需要。
    • -s3.port.https——另開一個 HTTPS 埠、原 -s3.port 保持明文（雙軌）。
  • 行為實測：
    • 只給 cert/key、不給 -s3.port.https → -s3.port=8333 直接變純 HTTPS。log：Start Seaweed S3 API Server ... at https port 8333。對它送明文回 400 Client sent an HTTP request to an HTTPS server。這正是 D2 要的「關明文」形態。
    • 給 -s3.port.https=8443 → log 出現兩行（https 8443＋http 8333），明文仍在。不要用這個旗標。
  • 健康檢查：image 內只有 busybox wget（無 curl、無 openssl）。
    • wget -q -O /dev/null http://127.0.0.1:8333/healthz → 失敗（400）。現行 compose 健康檢查會變紅。
    • wget -q --no-check-certificate -O /dev/null https://127.0.0.1:8333/healthz → 成功。
    • 想驗憑證可設 env SSL_CERT_FILE=<ca.crt> 給 wget（實測成功），但健康檢查只需判「活著」，--no-check-certificate 已足夠且不必再掛 CA 進這顆容器。
  • weed shell 建 bucket（安裝器 install.sh:1875）與 weed filer.copy ... http://localhost:8888/...（install.sh:1922）：完全不受影響——它們走 master 9333／filer 8888（HTTP＋gRPC），不經 S3 埠。實測建 bucket、列 bucket、filer.copy 都成功。

🔴 母卡沒列的缺口：filer／master／volume 埠在內網明文且免帳密

server 模式預設把 master 9333、filer 8888、volume 8080（及其 gRPC 1xxxx）都聽在容器 IP 上。從同網段另一顆容器實測：

wget http://guidant-seaweedfs:8888/buckets/testbkt/a.txt  → 直接讀到檔案內容（無帳密）
wget http://guidant-seaweedfs:9333/cluster/status          → 成功
wget http://guidant-seaweedfs:8080/status                  → 成功

production compose 的 default 網段上有 api／socketio／worker／fe／db-init 全部成員，任何一顆被打穿都能繞過 S3 的 TLS 與帳密直接讀寫全部客戶檔案。S3 埠加密若不同時處理這三個埠，#124 的威脅只修了一半。

可行解法（已實測）：加 -ip=127.0.0.1 -ip.bind=127.0.0.1 -s3.ip.bind=0.0.0.0。結果：

  • 容器內只剩 S3 8333 聽在全部介面，其餘全部只聽 127.0.0.1；
  • 同網段容器打 8888／9333 → Connection refused；
  • 容器內 weed shell（建 bucket）、weed filer.copy（灌 storage-seed）、健康檢查都照常——因為安裝器本來就是 docker exec 進同一顆容器執行。

對 ② 的結論：compose 加 -s3.cert.file／-s3.key.file（不加 -s3.port.https）＋-ip=127.0.0.1 -ip.bind=127.0.0.1 -s3.ip.bind=0.0.0.0；健康檢查改 https://127.0.0.1:8333/healthz --no-check-certificate；安裝器建 bucket／灌檔兩段不用改。

§3

B. 主系統 S3 客戶端怎麼餵 CA

查了什麼：jedi-file-upload 原始碼、.venv 內 minio 7.2.20 原始碼，再在 docker 網路內實連 TLS SeaweedFS。

看到什麼

  • SDK：minio（不是 boto3）。jedi_file_upload/infra/adapter/minio/minio_adapter.py:59-64：

    Minio(config.endpoint, access_key=..., secret_key=..., secure=config.secure)

    SeaweedFS adapter（seaweedfs_adapter.py:6）只是繼承它，同一條路。沒傳 http_client，所以套件目前沒有任何傳 CA 的參數入口。

  • minio 7.2.20 api.py:168-174：沒給 http_client 時自建 urllib3.PoolManager(cert_reqs='CERT_REQUIRED', ca_certs=os.environ.get('SSL_CERT_FILE') or certifi.where())——唯一不改套件的入口是 env SSL_CERT_FILE。

  • 實測（容器內、endpoint guidant-seaweedfs:8333）：

    情境 結果
    secure=False（今天 DB 裡的值）連 TLS 埠 InvalidResponseError ... 400 Client sent an HTTP request to an HTTPS server
    secure=True、不設 SSL_CERT_FILE SSLCertVerificationError（自簽 CA 不在 certifi）
    secure=True、SSL_CERT_FILE=ca.crt 成功（put_object、list_buckets）
    同上但 endpoint 用 IP（不在 SAN） SSLCertVerificationError——hostname 驗證有作用，SAN 寫 guidant-seaweedfs 正確

🔴 陷阱：SSL_CERT_FILE 是「取代」不是「追加」

同一行程設 SSL_CERT_FILE=<只有內部 CA> 後，實測：

客戶端 打 https://pypi.org
httpx 0.28（openai／anthropic SDK、AI 閘道走這條） 失敗
Python 標準庫 ssl／urllib 失敗
requests 成功（它看 REQUESTS_CA_BUNDLE，不看這個）

也就是說 api／worker 設了它，AI 閘道打外部模型、寄信、Drive 等所有對外 HTTPS 會全斷。改成「certifi 內容＋內部 CA」合併檔後，httpx、urllib 打公開站與打 SeaweedFS 都成功（已實測）。

對 ② 的結論：兩條路擇一——

  1. 不動套件（建議先走）：image build 期或容器啟動時產「certifi bundle＋內部 CA」合併檔，SSL_CERT_FILE 指它。陷阱是 certifi 路徑在 Nuitka 編譯產物內要實查，且合併檔要在 CA 輪換時重產。
  2. 動套件：MinioUploadConfigDTO 加 ca_cert_file，adapter 有值時自建 urllib3.PoolManager(ca_certs=...) 傳 http_client。影響只在主系統這條、不污染行程全域，較乾淨；但屬 jedi 套件異動，要決策者點頭＋發版。agent 側（③）用同一個套件嗎要另查——agent 若自己包 minio 就各自處理。

另外 managed_file_upload_service.py:109／123 的 secure 缺值預設 false 與安裝器三處 secure: false（母卡已列）都要翻；DB 裡舊值不翻，升級後第一個上傳就是上表第一列的錯誤。

§4

C. Redis 連線點全清單

查了什麼：BE 全 repo（排除 .venv／test／docs）＋ jedi-python-package 全部套件（排除 archive／tests／dist）grep redis|Redis(|from_url|StrictRedis|REDIS_*|FlaskRedis|message_queue，逐筆開檔確認；並比對 .venv 內 jedi-iam 1.4.8 與源碼一致（diff 無差）。

結果：真正「建連線」的只有三條，其餘都是這三條的呼叫者或純註解。

# 位置 建法 吃哪個設定 TLS 入口
1 core/extensions.py:30 FlaskRedis()，core/app_factory.py:178 init_app(app, decode_responses=True) redis.Redis.from_url(app.config["REDIS_URL"]) config/config.py:152 REDIS_URL——寫死 redis://、不看 REDIS_SSL 只能靠 URL：改 rediss://...?ssl_ca_certs=...&ssl_check_hostname=true
2 core/app_factory.py:180-195 SocketIO message_queue python-socketio RedisManager 吃 URL REDIS_USER／REDIS_SECRET／REDIS_HOST、REDIS_SSL 切 rediss 同上，URL query；目前沒帶 CA 參數
3 jedi-iam jedi_iam/common/utils/redis_client_util.py:10-50 RedisClient() redis.Redis(host=, username=, password=, ssl=, ...)，**port 不帶（固定 6379） 經 get_setting() → 主專案 common/iam_ports.py EnvSettingsReader（os.getenv，REDIS_SECRET 另組 JSON） 已完備**：REDIS_SSL=true 時強制 ssl_cert_reqs=required＋ssl_check_hostname=True，REDIS_SSL_CA_CERTS 有值就帶 ssl_ca_certs

#3 的呼叫者（每次操作 new 一顆 RedisClient）：

  • jedi-iam MFA：mfa/app/service/email_service.py:59,93、mfa/infra/email/adapter/email_adapter.py:9、mfa/app/service/attempt_guard.py:36——這就是 compose 注解說「MFA 套件只讀 REDIS_SECRET」那條。
  • 主專案：common/util/redis_rate_limiter.py:25（API 節流＋AI 閘道每分鐘上限，core/plugins/ai_gateway.py:171）、common/middleware/socketio_limits.py:44（socketio 同帳號連線數）、core/plugins/ai_bot.py:37（聊天紀錄）、infra/survey/adapters.py:29（問卷共編線上名單）。

#1 的呼叫者：app/cloud_integration/service/google_drive_integration_service.py:117,160,163（Drive OAuth state）。

其他 jedi 套件（survey／ai-bot／detection／ai-gateway）只有註解或 port 介面提到 Redis，不自建連線；jedi-common 有一支 jedi_common/session/redis/redis.py 的 FlaskRedis() 實例，主專案與各套件都沒 import 它，等同死碼。

實測（BE .venv → 本機 TLS-only Redis，--port 0 --tls-port 6379）：

情境 結果
from_url("rediss://...?ssl_ca_certs=<ca>") 成功
from_url("rediss://...") 不帶 CA CERTIFICATE_VERIFY_FAILED
from_url("redis://...") 打 TLS 埠 Connection closed by server（D2 關明文生效）
FlaskRedis＋REDIS_URL=rediss://...?ssl_ca_certs= 成功（set／get）
jedi-iam RedisClient（REDIS_SSL=true＋REDIS_SSL_CA_CERTS） 成功

🔴 陷阱：redis-py 5.2.1 rediss:// 預設不驗 hostname

docker 網路內用容器 IP（不在 SAN）連：只帶 ssl_ca_certs → 成功；加 &ssl_check_hostname=true → 失敗。也就是 #1、#2 走 URL 時必須明帶 ssl_check_hostname=true，否則只驗「是這把 CA 簽的」、不驗「是 guidant-redis」。#3 套件端已自帶，不受影響。

對 ② 的結論：

  • CA 路徑的 env 名沿用 jedi-iam 已有的 REDIS_SSL_CA_CERTS（新增 env 前必查既有的鐵則），BE config.py 讀同一個名字組 URL，不另創。
  • config.py:152 依 REDIS_SSL 切 scheme 並補 ?ssl_ca_certs=<quote 過的路徑>&ssl_check_hostname=true；app_factory.py:186-187 同樣補 query，並改用 quote_plus 包密碼（現行 socketio 那條沒 quote，與 config.py:152 不一致——密碼含 @／:／/ 會組壞 URL，安裝器若只產英數字則暫無症狀）。
  • 三個 BE 容器（api／socketio／worker）都要 REDIS_SSL=true＋REDIS_SSL_CA_CERTS=<容器內 CA 路徑>＋掛 CA 檔。
  • Redis 自己的 compose 健康檢查要改 redis-cli --tls --cacert <ca>（image 內 redis-cli 支援 --tls，已實測）。Redis 服務那顆要掛自己的 cert／key／ca。
§5

D. eventlet＋rediss:// 訊息佇列

查了什麼：本機起 TLS-only Redis（含照 compose 的 guidant-socketio ACL：resetchannels "&flask-socketio" -@all +@connection +publish +subscribe +unsubscribe），寫一支最小 Flask-SocketIO server（eventlet.monkey_patch()、async_mode="eventlet"、message_queue=rediss://guidant-socketio:...@localhost:16379/0?ssl_ca_certs=<ca>&ssl_check_hostname=true），client 連上 namespace 後，另起一個獨立行程（模擬 api／worker）只透過 SocketIO(message_queue=url).emit(...) 推播。

看到什麼

情境 結果
不帶 message_queue（對照組），外部行程 emit client 收到 []（預期：沒佇列就收不到）
帶 rediss message_queue＋CA＋hostname 檢查 server log redis backend initialized.，client 收到 [{'x': 1}]
帶 rediss 但不帶 CA server 照常起、HTTP 握手正常，log 只有 Cannot receive from redis... retrying in 1 secs 無限重試，推播全掉

eventlet 0.40.4 的 ssl monkey patch 與 redis-py 5.2.1 TLS 在此組合下沒撞到歷史坑；最小 ACL 帳號也夠用。

🔴 陷阱：缺 CA（或 CA 路徑錯、檔案沒掛進容器）時，socketio 容器健康檢查是綠的、前端連得上，只是「別的行程推過來的訊息」永遠到不了——症狀會被誤判成前端或業務邏輯問題。

對 ② 的結論：可行，照 C 的 URL 組法即可。驗收時一定要做跨行程推播（例如觸發一個由 api／worker 推給前端的事件），只看 socketio 容器起得來不算數；並 grep socketio log 確認沒有 Cannot receive from redis。

打折說明：本測是用最小 server 驗「eventlet＋rediss＋ACL」這個組合，沒有跑 RUN_MODE=socketio python main.py——DEV .env 的 Redis 指向 189 的明文 Redis，要跑完整 main.py 得改 .env 指本機 TLS Redis 並帶齊 DB 等設定，超出只讀範圍。套件版本與 BE 完全相同，風險在「main.py 有沒有在別處另建連線」，C 段已逐檔確認沒有。② 在 188 實裝時補跑一次完整服務即可覆蓋。

§6

E. worker 行程用哪條連線

main.py:152 三種模式都跑 create_app()，core/app_factory.py:178 的 redis_client.init_app(...) 不分模式一律執行（#1）；socketio 的 #2 只在 enable_socketio（socketio 模式）才建。worker 實際打 Redis 的是：

  • #3 RedisClient：AI 閘道每分鐘上限（redis_rate_limiter）、AI 聊天紀錄（core/plugins/ai_bot.py）；
  • #1 FlaskRedis：連線物件會建（from_url 是 lazy，不打不連），worker 目前沒有呼叫者，但設定錯了一樣是潛在炸點。

app/background_job/ 內沒有任何 Redis 呼叫——撿單走 DB。

對 ② 的結論：worker 不用特別處理，跟 api 一樣設 REDIS_SSL＋REDIS_SSL_CA_CERTS＋掛 CA 即兩條都切到。驗收：worker 容器內觸發一次 AI 呼叫（會打節流計數），log 無 Redis 連線錯誤。

§7

給 ② 的開工清單

憑證

  1. 安裝器沿用 agent CA（install.sh:1632 起），簽兩張終端憑證：SAN DNS:guidant-seaweedfs,DNS:localhost,IP:127.0.0.1／DNS:guidant-redis,DNS:localhost,IP:127.0.0.1，EKU serverAuth。注意該段簽完會 rm ca.srl，新簽要再帶 -CAcreateserial。
  2. 私鑰檔權限要讓 redis 與 seaweedfs 容器內的執行身分讀得到（本測用 644 跑通，實際 uid 未查，② 裝機時確認）；CA 私鑰不掛進任何容器。

SeaweedFS（compose guidant-seaweedfs） 3. command 加 -s3.cert.file／-s3.key.file；不要加 -s3.port.https（會留明文雙軌）。 4. command 加 -ip=127.0.0.1 -ip.bind=127.0.0.1 -s3.ip.bind=0.0.0.0，把 filer 8888／master 9333／volume 8080 收回容器本機（見 A 段缺口；建議與決策者確認後併入本棒）。 5. 健康檢查改 wget -q --no-check-certificate -O /dev/null https://127.0.0.1:8333/healthz。 6. 安裝器 weed shell 建 bucket、weed filer.copy 灌檔兩段不用改（已實測）。

S3 客戶端（api／socketio／worker） 7. 選 B 段兩條路之一。若走 SSL_CERT_FILE：必須是 certifi＋內部 CA 合併檔，否則 AI 閘道與所有對外 HTTPS 斷線。 8. DB system_configs STORAGE_CONFIG secure 翻 true（安裝器三處＋升級腳本＋managed_file_upload_service.py:109/123 預設值）。

Redis 9. compose guidant-redis：--port 0 --tls-port 6379 --tls-cert-file --tls-key-file --tls-ca-cert-file --tls-auth-clients no；健康檢查改 redis-cli --tls --cacert ...。 10. config.py:152 依 REDIS_SSL 切 scheme，補 ssl_ca_certs＋ssl_check_hostname=true；app_factory.py:186-187 同步並改用 quote_plus。 11. env 名沿用 REDIS_SSL＋REDIS_SSL_CA_CERTS（jedi-iam 已在讀），三個 BE 容器都設；.env sample 與 deployment-env.md 補 REDIS_SSL_CA_CERTS 一行。 12. jedi-iam RedisClient 不用改。

驗收必做（只看容器起得來不算） 13. 上傳＋下載一個檔案（S3 TLS）；AI 呼叫一次（certifi 合併檔沒弄壞對外 HTTPS）；MFA 寄 Email OTP 一次（#3）；Drive 授權一次（#1）；跨行程 socketio 推播一次（#2）。 14. grep 三容器 log：無 CERTIFICATE_VERIFY_FAILED、Cannot receive from redis、HTTP request to an HTTPS server。 15. 從 fe 容器 wget http://guidant-seaweedfs:8888/、redis-cli -h guidant-redis ping（明文）都要失敗。 16. 舊庫升級排練：升完 secure 已翻 true、既有檔案讀得到。

agent 側（③，給 CM-2489 參考） 17. agent compose :306-314 的 init 容器是另一顆容器用 weed shell -master=guidant-agent-seaweedfs:9333 連——若 agent 那顆也照第 4 點收 bind，這段會連不上，要改成 docker exec 進同一顆或保留 master 對內網開放。