FR-080 宿主側盤點：今天這個系統實際是怎麼組裝／部署／跑的

盤點日期：2026-09-09｜branch feature/FR-075｜HEAD c2bf55d6 盤點範圍：主專案（宿主）compliance-manager-be。套件本身只在「宿主怎麼呼叫它」的範圍內查證。 所有查證皆唯讀（Read / grep / SELECT）。DB 查詢對象：DEV 192.168.50.188:25432/guidant_ai_dev（cm_app）。

---

A1. core/app_factory.py 的 register_* 逐條

create_app(enable_socketio, enable_scheduler, integrity_context) 共 608 行，是唯一組裝根。 七支套件插件在此註冊（另有 10 支走 api/<mod>/__init__.py 的 create_blueprint，見 A1-b）：

同一函式內的其他組裝動作（非 register_* 但屬接線）：

• configure_logging()（:71-73）— jedi-common，掛 DBLogHandler 到 7 個頂層 logger（系統 log 寫 DB system_logs 是功能不是除錯）
• init_database(db_uri)（:131）— jedi-common，建 engine ＋ session factory
• app.config.update(get_runtime_config())（:144-146）— 從 DB system_configs / ROOT / RUNTIME_CONFIG 覆寫營運參數
• start_forwarding_chain(LogForwardingConfig(...))（:155-165）— jedi-log-forwarding，syslog／GELF 轉發，起 listener＋watcher 執行緒
• redis_client.init_app(app)（:168）／socketio.init_app(..., message_queue=redis_url)（:179-186，僅 socketio 模式）
• register_error_handlers(app)（:235，jedi-common）＋ _register_local_error_handlers(app)（:236，本地三支：RequestEntityTooLarge／BpmnTopologyError／OtpResendTooFrequentError）
• init_request_context_isolation(app)（:251）＋ _make_reject_oversized_request_hook（:256）＋ init_app_interceptor(app)（:259）
• container.wire(modules=get_di_wire_modules())（:275-281）— DI wiring，全部後續接線的時序紅線
• register_stage_hooks_to_registry(...)（:425-426）— flow_control 的 stage handler／precondition 註冊進 registry
• app.extensions['di_container'] = container（:431）— 背景 job / adapter 延遲解析的唯一入口
• configure_socket_identity(_user_service_provider, _login_token_service_provider)（:437-440）— jedi-iam socket 身分
• _register_socketio_namespaces()（:481-482，僅 socketio 模式）
• init_license_readonly_gate(app)（:488-489）— license readonly/locked 全域攔寫入
• init_scheduler(app, worker_pool_size)（:493-499，僅 enable_scheduler=True）

A1-b. 走 api/<模組>/__init__.py::create_module() 的第二批插件接線

main.py:136-157 迴圈 import api.<name> 並 register_blueprint(create_module())。以下模組的 create_module() 實際上是「組 adapters → 向套件要 blueprint」：

合計：18 支套件在宿主有顯式接線點（8 在 app_factory + 10 在 api/*）。

A1-c. config/app_modules.py 還登記哪些主專案模組

REGISTERED_APPS（config/app_modules.py:7-84）現有 31 個條目（另 8 個已註解退役：auth／captcha／resource／system_menu／notification／upload_file／log／issue）：

bulletin, system_config, notify_config, survey, flow_engine, ai, task_survey, device,
report, subtask_status_history, user_auth_provider, label, feedback,
project_summary_report, module_frame, translate, oscal, project, participant,
ai_dashboard, flow_control, information_system, cloud_integration,
evidence_classification, remote_agent, version, detection_tools, license, setup,
log_forwarding

（實測 ls api/ 有 33 個目錄；find api -name '*_route.py' 有 72 支 route 檔。）

載入採 fail-fast：任一模組 import 失敗或缺 create_module() 直接 RuntimeError 終止啟動（main.py:140-154）——原本是 warning-only，症狀是「整組 API 無聲消失」。

A2. di_containers/ 的規模與 port adapter 盤

• 檔案：di_containers/ 下 40 支非 __init__ 的 .py（含 dashboard_apis/ 12 支）；總 5554 行。
• Container 類別：39 個子 Container class ＋ 1 個根 Containers（di_containers/containers.py:76），根內 providers.Container( 出現 39 次。
• 最大三支：flow_control/flow_control_containers.py 720 行、oscal/oscal_containers.py 507 行、module_frame/module_frame_containers.py 258 行。
• 循環依賴以 override_providers 事後補：containers.py 內共 11 處（:156, :167, :247, :250, :287, :292, :304, :311, :333, :341, :346, :378, :383, :401），把「宣告順序解不了的雙向依賴」補回去。這是接線盤的複雜度來源，也是 sys.setrecursionlimit(5000) 的成因（di_containers/containers.py:51-73 有完整說明：deepcopy 整張 provider 圖需 ~2000 frames，Python 預設 1000，額度不足時錯誤被 dependency_injector 重包成誤導性的 NonCopyableArgumentError）。
• DI wire 模組數：config/di_modules.py 動態 rglob 掃描（release 模式改讀 build 期凍結的 config/di_modules_static.py）。實測全 repo 含 @inject 的模組 73 支。

「替套件實作 port adapter」的 container / 檔案完整清單

宿主接線盤的實際長度：15 支專職 wiring／adapter 檔（合計 2004 行）：

DI container 內把 adapter 註冊成 provider 的位置（樣本）： di_containers/evidence_classification/evidence_classification_containers.py:68-72（五支 Singleton）、 di_containers/detection_tools/detection_orchestration_containers.py:44,104、 di_containers/survey/survey_containers.py:80、 di_containers/remote_agent/remote_agent_containers.py:32-36（DetectionLifecycleListener／DetectionTaskPayloadProvider／RemoteAgentReconQuery）、 di_containers/agent_task/agent_task_containers.py:14。

接線盤總結：15 支 wiring/adapter 檔（2004 行）＋ 5554 行 DI container ＝ 約 7,558 行純組裝碼，服務 18 支套件。

A3. 宿主直接 import 套件 infra 層（繞過套件 API 直摸表）

app/ 層 6 處（違反 DDD 分層規範最明顯的一批）：

common/ 層：0 處（test/test_module_boundaries.py 有守衛測試擋反向 import）。

infra/ 層 47 處 import 套件 ORM model / mapper（宿主 model 直接繼承／外鍵指向套件表），是「拆成服務後會斷掉」的第一層：

按檔案計數（grep -c 前十）：infra/flow_control/repository/flow_control_job_repo_impl.py 16 次、di_containers/flow_control/flow_control_containers.py 14、di_containers/auth/auth_containers.py 14、infra/flow_control/repository/flow_control_project_repo_impl.py 12、di_containers/detection_tools/detection_tools_containers.py 11、infra/readmodel/audit/flow_control_dashboard_repo_impl.py 7、infra/flow_control/repository/job_export_query.py 7。

---

B4. main.py 的 RUN_MODE 與 process 形態

只有一支入口（Nuitka 編譯目標只能有一個，main.py:1-5）。RUN_MODE 環境變數切換，非法值直接 SystemExit（:67-70）。

模式裁剪表（main.py:9-18，逐條與程式碼對得上）：

gunicorn worker 數：GUNICORN_WORKERS 環境變數，預設 4（main.py:258）；timeout GUNICORN_TIMEOUT 預設 120s（:260）。gunicorn 是內嵌的（BaseApplication 子類 _EmbeddedGunicorn，main.py:239-269），不是外部 gunicorn main:app——因為編譯後是密封 binary。 post_fork 做三件事（main.py:200-237）：① engine.dispose(close=False) 丟掉繼承的 DB 連線池（不做會撞 DuplicatePreparedStatement，實測每 3 個請求炸 1 個 500）；② register_gunicorn_master(server.pid)（tamper 終止路徑）；③ restart_after_fork() 重建 log 轉發鏈的 listener/watcher 執行緒。

第三種 process：沒有。 沒有 celery、沒有獨立 worker 進程、沒有 cron 容器。所有背景工作都在 api 模式的 gunicorn master process 內，靠 APScheduler BackgroundScheduler（thread pool）跑。

全部背景排程（core/scheduler.py）

主 scheduler init_scheduler(app, worker_pool_size=DRIVE_SYNC_WORKER_POOL_SIZE 預設 4)，ThreadPoolExecutor(max_workers=pool)，UTC：

socketio 模式的獨立 scheduler init_integrity_scheduler（:85-113）：ThreadPoolExecutor(max_workers=1)，只掛 integrity_spot_check 一支。

非 scheduler 的長駐／臨時 thread

這批 threading.Thread(...).start() 是 fire-and-forget 通知，沒有佇列、沒有重試、沒有死信。拆服務時這是「非同步邊界已存在但沒有基礎設施」的訊號。

SocketIO namespace（僅 socketio 模式）

config/socketio_namespaces.py:41-52，共 2 個：

• /socket/notification → app.notification.handler.notification_socketio_handler.NotificationSocketioHandler（宿主）
• /socket/fill-survey → jedi_survey.app.handler.fill_survey_socketio_handler.FillSurveySocketioHandler（套件）

B5. 對外 I/O 全清單

B6. DB：RLS 注入機制、schema、policy、view

RLS session 變數注入點：jedi-common/jedi_common/session/database/db.py::session_scope()（:85-127）。 逐條 SET LOCAL：

SET LOCAL row_security = on                       (:93)
SET LOCAL app.user_id = '<user_ctx.id>'           (:94-96)
SET LOCAL app.can_manage_orgs = 't'               (:97-99)
SET LOCAL app.is_super_admin = 't'/'f'            (:103-105)
SET LOCAL app.allowed_tenant_paths = '...'        (:107-109)  # 有值時
SET LOCAL app.allowed_org_paths = '...'           (:112-114)  # 有值時
--- 無 user context（背景 job / worker）分支 ---
SET LOCAL app.is_super_admin = 't'                (:116-118)  # RLS bypass

另有 :58-66 的 app.is_super_admin / app.can_read_all_orgs 設定路徑。 :88 註明「非 PostgreSQL（如 evidence-agent 的 SQLite）沒有 RLS、也不吃 SET LOCAL」——即這條鏈已經有一個非 PG 消費者。

DEV 實測（guidant_ai_dev）：

RLS 啟用的 32 張表逐張： compliance.{agent_tasks, detection_execution_groups, detection_executions, flow_templates, module_frames, remote_agent_enroll_tokens, remote_agents}； config.{detection_profile_versions, detection_profiles, detection_tool_profiles_deprecated_20260803, job_execution_detection_tool_agents, job_execution_detection_tools, tenant_detection_tool_configs, tenant_license_events, tenant_license_suspensions, tenant_licenses}； oscal.{ap_docx_parse_jobs, ar_xlsx_parse_jobs, ssp_docx_parse_jobs, ssp_excel_parse_jobs}； public.{bulletins, devices, drive_folder_mappings, drive_sync_jobs, feedback_issues, org_units, roles, system_configs, tenants, users}； survey.{survey_folders, surveys}。

觀察：compliance.projects、compliance.job_executions、oscal.system_security_plans 等核心業務表沒有 RLS——租戶隔離在那些表上靠應用層。

DB view 共 4 張（information_schema.views，實測依賴以 pg_depend/pg_rewrite 反查）：

vw_user_job_queue 的 Python 側 view model 在 infra/readmodel/tasks/vw_user_job_queue.py（94 行）；消費者是 my_grc_jobs_query.py 與 flow_control_dashboard_repo_impl.py。

B7. 宿主 readmodel／跨疆界聚合查詢

infra/readmodel/（1753 行，9 支查詢 ＋ 5 支 __init__）是專為此設立的「不隨套件走」目錄，檔頭（infra/readmodel/__init__.py:1-67）明寫動機：這些 SQL 字串裡藏著對其他模組資料表的依賴，grep 守衛掃不到（表名在字串裡不是 import）、harness 也測不出。

readmodel 之外，仍有跨疆界 JOIN 留在各模組（grep -c '\.join(' 全 infra 排名）： infra/flow_control/repository/job_export_query.py（7，含 7 個套件 infra import）、 flow_control_job_repo_impl.py（6 join／16 套件 import）、 infra/associations/repository/job_execution_device_mapping_repo_impl.py（4）、 infra/flow_control/repository/job_import_lookup_query.py（3／5 import）、 infra/project_summary_report/repository/project_summary_report_repo_impl.py（1）。

「拆成服務後會斷掉的查詢」清單＝上表 9 支 ＋ vw_user_job_queue view ＋ flow_control 那 4 支寫讀混合的 repo_impl。 readmodel 已把純讀的部分正名收攏，但 infra/flow_control/repository/ 底下的寫讀混合 repo（16 次套件 infra import）尚未拆——那批既 JOIN 跨疆界又寫入，是最難拆的。

---

C8. 出貨的容器組成

canonical 是 docker/production/docker-compose.yml（478 行，含大量踩坑註解），scripts/build/build_bundle.sh 把它連同 image tar 封成 guidant-ai-<版號>.tar.gz。

六個服務 ＋ 一個 one-shot：

有 nginx／gateway 嗎：有，就是 guidant-fe（nginx）。它同時是靜態檔伺服器與 API gateway，是整套系統唯一對外入口。沒有獨立的 API gateway 元件。

容器互連：同一個 compose project（name: guidant），走 compose 預設 bridge network，以 container_name 當 DNS（guidant-db、guidant-redis、guidant-seaweedfs:8333、guidant-api:8000、guidant-socketio:8002）。啟動順序靠 depends_on: condition: service_healthy（x-guidant-common:126-133：BE 等 db+redis+seaweedfs 三者 healthy）——註解明寫「這條鏈只在同 project 內成立，那正是 DB/Redis 與 BE 刻意同 project 的原因」。

bundle 收哪些 image（build_bundle.sh:84-94）：guidant-ai-be、guidant-ai-fe、guidant-ai-init、postgres:16、redis:7-alpine、chrislusf/seaweedfs:3.99 — 6 顆，air-gap 可裝。

build 管線（scripts/build/README.md）：build_all.sh --all（⓪ assert_db_current.sh DB 前置斷言 → Nuitka 編譯 15-20 分 → smoke → 三顆 image）→ build_bundle.sh 封包。build 機是 188 的 /opt/guidant-ai-be（git clone，更新走 git pull）。smoke 連的是安裝版 stack 的 guidant-db 容器、用 cm_app（受 RLS 的帳號，＝出貨實況）。

建庫 vs 升級（scripts/init/README.md）：scripts/init/ 管「從無到有」（02-schema.sql 產生檔：5 schema／176 表／103 policy／82 function／18 trigger），scripts/sql/ 管增量 migration；同一顆 init image 換 MODE=migrate 即為 migration 容器（刻意不分兩個 service，避免兩份連線設定各自演化）。

C9. remote-agent 是不是獨立部署

是——而且是兩種不同的 agent，都是獨立 process、獨立 repo：

(a) evidence-agent（檔案 agent） — 獨立 repo ~/Projects/Billows/Audit-Manager/evidence-agent/：

• 定位（該 repo CLAUDE.md）：「把 jedi-file-upload 套件包成一個獨立可跑的極小 REST 服務 + Docker」，裝在**客戶自有設備（Linux）**上，binary 不存雲端磁碟。
• 不連雲端 DB：自帶本地單檔 SQLite，只有 upload_files 一張表。「雲端 ↔︎ agent 只透過 REST 講話」。
• 單租戶、無 RLS。出貨走 deploy/Dockerfile.runtime ＋ build_compose_bundle.sh（compose 形態，自己的交付包）。
• 協定定義處：宿主側 infra/upload_file/remote_agent_adapter.py（273 行）——save_file／get_file／delete_file(s)／convert_to_pdf；_request()（:176-204）在 mode=full 下 httpx.Client(verify=build_cloud_mtls_context(...)) ＋ Authorization: Bearer <JWT>，走 https；_verify_integrity（:113）用 SHA-256 對實際 bytes 重算，信任根是雲端 upload_files.sha256。
• 它是「宿主的 storage backend」：走 jedi-file-upload 的 storage type remote_agent（common/code/file_storage_type.py，宿主定義因為「客戶端檔案 agent 是雲端部署概念，屬 caller 業務知識」）。

(b) 檢測 agent（detection scan agent） — 協定在 jedi-remote-agent 套件：

• 套件職責（jedi_remote_agent/__init__.py:1-28）：enroll（一次性 token 自我註冊 → 內部 CA 簽 server 憑證回給它）、heartbeat（更新 last_seen_at，順手把待辦派工夾帶回去＝polling 派工）、agent task 狀態機（pending→dispatched→running→succeeded/failed/cancelled）、雙向認證原語。
• 協定：REST（blueprint 在套件內，plugin.py:300-303 依 ROUTE_TABLE 掛，宿主提供 admin_required 守門）＋ mTLS ＋ RS256 短效 JWT（common/agent_auth/tls.py:14 build_cloud_mtls_context、jwt_util.mint；AGENT_JWT_TTL_SEC 預設 60s）。
• agent 主動撥出（agent_enrollment_service.py:3）：「bootstrap 用 token + TLS；穩態 heartbeat 走 mTLS，不帶 user JWT」；指紋變動自動更新 ＋ 留痕。
• 宿主設定：config/config.py:261-271 的 11 個 AGENT_*（AGENT_AUTH_MODE 預設 none＝demo 形態、CA cert/key、JWT key pair、cloud client cert/key、AGENT_HEARTBEAT_INTERVAL_SEC=300、AGENT_CERT_VALID_DAYS=3650、AGENT_JWT_TTL_SEC=60）。憑證以唯讀 bind mount 內外同路徑掛進容器（compose :177，註解明寫「掛在別處等於沒掛，症狀是服務全綠、只有 agent 連不上」）。
• DB 側（DEV 實測 \d compliance.remote_agents）：agent_type 預設 'file_storage'、capabilities jsonb 預設 ["file_storage"]、base_url、device_fingerprint、status、last_seen_at、agent_version、hardware_info——一張 registry 表同時承載兩種 agent。RLS 啟用。

C10. License Center 的交互

不只是「簽好的 License 檔」——有三條 runtime HTTP 通道，全在 jedi-license-runtime 套件內：

設定來源：config/config.py:303-313（LICENSE_ACTIVATION_SERVER_URL 預設 http://127.0.0.1:5062、LICENSE_CENTER_API_TOKEN 預設空）；經 api/license/__init__.py:82-87 進 LicenseConfig，並經 common/integrity/adapters.py:49,191-192 進 IntegrityConfig（integrity 也認得 LC）。

信任邊界仍然清楚（license_verification_service.py:344-347 明寫）：「兩 repo 零依賴——這裡只打 HTTP，不 import license_center 源碼。開通伺服器已核對序號合法性，但收到照後仍走 activate_license 完整驗章＋（host 版）指紋核對，不因來源是開通伺服器就信任（設計裁示：BE 是唯一信任邊界）」。無 DB 層共用（LC 獨立 DB license_center_{dev,stg}，migration 走 LC 自己的 scripts/sql/，不進主專案 schema_migrations）。 離線路徑仍在：LC 主機上跑 license-center sign-manifest（build_release.sh:955 的 air-gapped 保底）＋ 匯入授權檔。 公鑰表在 jedi_license_runtime.common.public_keys（build_bundle.sh 出貨前檢查有無 PROD 鑰，:940-960 附近）。

---

這個 codebase 已經有 5 個「已經是網路 API 邊界」的內部元件：

補充：BE 內部本身也已有一道「準服務邊界」——guidant-api 與 guidant-socketio 是同一顆 image 的兩個 process，靠 Redis message queue 做 socket 的跨進程訊息傳遞（app_factory.py:179-186）。這是唯一一處「同一份程式碼跑成兩個 process 並靠中介軟體通訊」的既有形態。

---

1. 宿主接線碼總量約 7,558 行（15 支 wiring/adapter 檔 2,004 行 ＋ di_containers 5,554 行），服務 18 支已插件化的套件；根 container 有 39 個子 container ＋ 11 處 override_providers 補循環依賴，deepcopy 需 5000 recursion frames。
2. 跨疆界查詢：infra/readmodel/ 9 支 1,753 行（最大一支 22 個 JOIN、7 疆界）＋ public.vw_user_job_queue 一張跨 3 schema／12 關聯的 view ＋ infra/flow_control/repository/ 4 支寫讀混合 repo（單檔 16 次套件 infra import）。前兩者已被正名隔離，第三批沒有。
3. 執行期只有兩個 process 形態（api / socketio）、零獨立 worker；全部背景工作（8 支 APScheduler job ＋ 約 20 處 threading.Thread fire-and-forget 通知）都在 api 模式的 gunicorn master 內，沒有佇列、沒有重試、沒有死信。

• 未實測啟動 BE 驗證 blueprint 實際掛出的 route 總數（只數了 72 支 *_route.py 檔）。
• di_containers/dashboard_apis/ 12 支檔的角色未逐支讀（從命名推測是 AI Dashboard 的資料源註冊，非 port adapter）。
• STG／POC 的 live compose 實況未 ssh 查證（本報告的容器組成以 repo 內 docker/production/docker-compose.yml 與 build_bundle.sh 為據）。
• 各套件內部有多少自己的跨疆界 SQL 未盤（本次只盤宿主側）。
• .build/bundle/guidant-ai-1.14.0/docker-compose.yml 是舊版產物快照，未與 canonical 逐行 diff。