运维¶

本页面面向已完成 YAML 配置、准备上线或承担值班职责的工程师。字段写法请参阅配置说明与字段手册。

生产入口¶

推荐使用仓库启动脚本：

cd backend
bash src/run_cg_rag_http.sh

Python 服务入口为 src.live_retriever_service。默认监听 0.0.0.0:8864，HTTP 前缀为 /cg-rag，MCP 路径为 /cg-rag/mcp/。生产环境应由 systemd、容器编排或等价进程管理器托管，并在前端配置访问控制与 TLS 终止。

Secret 与配置¶

API key 仅写入服务端环境变量或权限为 0600 的 secrets YAML；
非敏感配置放置于普通 YAML 或部署系统环境变量；
不得将 key 写入命令行、镜像层、日志、MkDocs 或 Git；
启动后通过 /health 的脱敏摘要确认配置生效，不输出原始 secret。

CG_RAG 优先读取进程环境中的 CG_RAG_*，缺失时由 YAML 补充，部分字段兼容 QUESTION_GENERATED_APP_*。完整优先级说明见配置说明，各 YAML key 的写法见字段手册。

启动前检查¶

目标 scope 的 corpus、dense index、BM25 index 可读且版本一致。
本地 embedding/rerank 模型存在，或远端 endpoint 在部署网络中可达。
generation endpoint/model/key 已成组配置；仅部署检索能力时可留空。
hydration sidecar 路径可写，且位于持久 cache 目录。
并发限制与 CPU、GPU、远端配额及请求超时相符。
非标准 HTTPS 端口或私有域名已加入出口防火墙与证书信任策略。

Hydration 离线门禁¶

正式部署前，须为 full、usual、usual_plus_law 三个 profile 中实际配置的全部 corpus 构建 hydration sidecar：

python scripts/build_hydration_sidecar.py \
  --env-file /path/to/question_generated_app.env \
  --resource-root /path/to/backend \
  --output /path/to/backend/src/.question_generated_app_cache/cg_rag_hydration.sqlite3

该脚本从各 profile 的 topks_by_stem 推导 corpus，不依赖固定数量。脚本在目标目录中构建临时 SQLite，严格校验 JSON、文档 ID、文件签名与 PRAGMA quick_check；全部来源通过后才原子替换正式 sidecar。构建失败、磁盘空间不足或目标路径与运行配置不一致时，旧库保持不变，部署须中止。

仓库的 release 部署器会在服务切换前强制执行该门禁，并比对运行中 CG_RAG health 的 sidecar path hash、plan fingerprint、configured corpus 数与 indexed corpus 数。后续 health 或 smoke 失败时将恢复上一份独立校验过的 sidecar；成功后仅保留一个可回滚版本。

Retriever Warmup¶

服务支持启动时 warmup，也支持显式 HTTP warmup：

curl --noproxy '*' -sS \
  -X POST http://127.0.0.1:8864/cg-rag/warmup \
  -H 'Content-Type: application/json' \
  -d '{"scopes":["full","usual","usual_plus_law"]}'

仅对首批真实流量将使用的 scope 执行 warmup。manager 当前仅常驻最后一个 active scope；依次预热多个 scope 会产生重复加载时间，但不会使其全部长期驻留。

重启后自动预热¶

CG-RAG 重启后，/cg-rag/health 的 ok 为 true（进程正在服务），但 ready 须等第一次 /cg-rag/warmup 将检索库加载完毕后才变为 true。为避免遗漏手动预热步骤，仓库提供了一个仅依赖标准库的工具脚本 backend/src/tools/cg_rag_warmup.py：等待 health 的 ok 为真，再对配置的 scope POST /cg-rag/warmup，最后等待 ready 为真。成功时退出码为 0，超时或失败时退出码为 1。

scope 默认为 full，可通过 --scopes 或环境变量 QUESTION_APP_CG_RAG_WARMUP_SCOPES 覆盖（多个 scope 以逗号分隔，最后一个将保持为当前 scope；留空则仅等待 ok）。
端口与前缀通过 --port、--prefix 或 QUESTION_APP_CG_RAG_PORT、QUESTION_APP_CG_RAG_HTTP_PREFIX 指定；已配置入站 token 时将其写入环境变量 CG_RAG_INBOUND_TOKEN，未配置则不发送 Authorization 头。
systemd 部署使用 deploy/construction-rag-cg-warmup.service.example（独立的 oneshot 单元）配合 deploy/construction-rag-cg-warmup.dropin.conf.example（为 CG 单元添加一条 ExecStartPost=-systemctl restart --no-block …）。重启、崩溃自动恢复、开机启动后均会自动预热，且 systemctl restart construction-rag-cg 仍立即返回。不得改用 PartOf=/WantedBy=：该配置会将预热任务并入同一 systemd 事务，导致 systemctl restart 须等待预热完成（耗时数分钟），而管理台重启 CG 仅等待 180 秒，启用 release 时将因此失败。预热结果可通过 systemctl status construction-rag-cg-warmup 查看。
以 tmux 方式启动服务（run_cg_rag_http.sh）时已内置相同的预热流程，无需额外安装该单元。

上线 Smoke¶

按顺序执行以下验证：

curl --noproxy '*' -fsS http://127.0.0.1:8864/cg-rag/health
curl --noproxy '*' -fsS http://127.0.0.1:8864/cg-rag/profiles
curl --noproxy '*' -fsS \
  -X POST http://127.0.0.1:8864/cg-rag/retrieve-rerank \
  -H 'Content-Type: application/json' \
  -d '{"query":"脚手架验收要求","scope":"full","topk":5}'

启用生成能力时，还须验证 /constrained-generate、/rag 与 /rag/stream。真实 provider smoke 须通过显式环境开关在 staging 或受控发布流程中执行，常规 CI 使用 mock，不依赖生产模型服务。

启用视觉识别时，先确认能力已就绪，再使用一张真实现场图片验证两种模式：

curl --noproxy '*' -fsS http://127.0.0.1:8864/cg-rag/health \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["vision"])'

curl --noproxy '*' -fsS \
  -X POST http://127.0.0.1:8864/cg-rag/vision/answer \
  -H 'Content-Type: application/json' \
  -d "{\"images\":[{\"data\":\"$(base64 -w0 smoke.jpg)\",\"mime_type\":\"image/jpeg\"}]}"

自由生成验证通过后，再验证 /cg-rag/vision/agentic：该接口同时覆盖 VLM 上游、进程内检索回调与引用校验，是视觉链路最具价值的单条 smoke。应检查返回的 citations 非空且 retrieval_docs 与之对应——citations 为空表明引用契约或检索未正常工作。

关键观测项¶

应持续观测 GET /cg-rag/health 的以下字段：

顶层 active_scope；
retriever.resident_scopes、retriever.load_count、retriever.last_load_time_ms、retriever.last_loaded_scope；
retrieve cache 的 entries/hits/misses/max_entries/ttl；
profile fingerprint id 与脱敏 summary；
hydration 的 enabled、path hash、plan fingerprint、configured/indexed corpora、lookup hit/miss/failure、build count 与 last error；
rerank 是否走远端 API、当前公开模型名；
generation 是否 configured、provider/model、thinking、streaming；
vision 是否 configured、model、图片与轮数上限（vision.configured 为 false 时，视觉接口全部返回 vision_not_configured）；
retrieval/generation capacity 的 max、active、queued、peak、rejected 与等待上限。

应用日志应按 request ID 聚合，重点告警 capacity.exceeded、service_error、stream_failed、hydration lookup failure、retriever 重复加载与 generation response invalid。启用视觉识别后还应关注 vision_upstream_error、vision_response_invalid 与 invalid_image 的发生比例：前两者指向 VLM 上游问题，后者通常源于调用方的图片处理异常。

视觉与文本生成共用同一个 generation 容量限制器。视觉请求的耗时远高于文本 constrained generation，因此当 capacity.generation 的 queued/rejected 上升时，应首先排查是否有批量视觉流量挤占配额。

发布与回滚¶

生产环境为单一 Git 检出目录，代码、依赖与运行数据同处一处。发布流程为：拉取目标提交、按需重建前端产物、重启受影响的服务窗口，再完成 health/retrieve/generation smoke。secret、SQLite、hydration sidecar 与语料软链接均不受 Git 跟踪，拉取操作不会覆盖它们。

各服务拥有独立的启动脚本，重启时仅启动受改动影响的服务：src/run_cg_rag_http.sh（CG_RAG）、src/run_question_generated_api.sh（Question API）、src/run_question_generated_web.sh（Web）。三者均会先关闭同名 tmux 窗口再重建，不得在正在运行的目录上手动覆盖 Python 文件。

视觉识别仅依赖配置与代码，不引入新的持久化资产：图片随请求传入并在内存中处理，回滚代码即可回退该能力，无需还原任何数据文件。

回滚条件至少包括以下情形：

health 不通过或目标 scope 不可用；
相同基准 query 的召回为空或来源字段出现明显退化；
generation 错误率、invalid response 或 timeout 显著上升；
SSE 无 final、取消后仍持续占用上游连接；
cache fingerprint、hydration 或 rerank 配置与发布预期不一致。

回滚操作为检出上一个已知良好的提交并重启对应服务，同时保留失败发布的脱敏日志与 request ID。索引或 sidecar 发生 schema/内容变更时，须将其作为独立版本化资产处理，不可仅回滚代码——这些资产不在 Git 中，须在回滚代码前单独备份并还原。

文档发布¶

CG_RAG MkDocs 使用严格构建：

cd backend
mkdocs build --strict

Cloudflare Pages 发布脚本为：

CG_RAG_DOCS_WRANGLER_ENV_FILE=/path/to/cg-rag-docs.env \
  bash scripts/deploy_cg_rag_docs_pages.sh

凭据文件须置于仓库外或被精确 ignore；发布完成后应核验自定义域名、sitemap 与搜索索引。

入站鉴权与默认监听¶

默认监听 127.0.0.1（QUESTION_APP_CG_RAG_HOST / cg_rag.host）。
在 question_app.secrets.yaml 中设置 cg_rag.inbound_token（或环境变量 CG_RAG_INBOUND_TOKEN）；Question API 会自动携带同一 Bearer。
未设置 token 且监听非回环地址时，启动将打印 WARNING，health config_issues 出现 cg_rag.inbound_auth_missing；仅在 CG_RAG_REQUIRE_INBOUND_AUTH=1 时才会拒绝启动。
OpenAPI /docs 默认关闭（cg_rag.expose_docs，默认 false）。

检查并清理 env.json 中的过期路径覆盖¶

查看 GET /cg-rag/health（需 Bearer）的 config_issues：若存在 retrieval.env_overrides_yaml，其中列出的是被进程环境固定的键名（不含路径值）。
对照 path_ids：同一 release 下，corpus_root / index_root / bm25_index_root 的 id 应属于同一套目录；混用说明 corpus 与索引来自不同 release。
编辑启动所用的 construction-rag-cg.env.json（或等价 env 文件），删除 QUESTION_GENERATED_APP_*_{CORPUS,INDEX,BM25}_ROOT 类残留键，使 YAML 或管理台写入的配置生效；或将其改为与当前 release 完全一致的三套路径。
重启 CG-RAG 后再查 health：config_issues 不再报 override，且三份 path_ids 对齐。
清理完成并确认稳定后，可按需开启 CG_RAG_STRICT_CONFIG_CONFLICTS=1，使配置冲突直接拒绝启动。