ZY Action Platform 运维工程师（SRE）使用说明

适用对象：SRE / 运维工程师 · 核心产品：P3 LightApollo（GitOps/漂移/配置/监控告警/Spoke Agent）+ 全平台启停/数据库/故障排查 + V5 可观测性（Prometheus /metrics、embed 单二进制、Docker 镜像、构建发布脚本）+ Swift 部署授权自检 · v5 对齐 wiki/docs 系列文档 · 冒烟脚本 smoke_apollo.sh 为准

1. 平台拓扑与端口

服务	端口	进程名	说明
Web 网关	80	gateway	SPA + 反向代理（/api→Foundry、/apollo-api→Apollo、/aip-api→AIP、/gotham-api→Gotham、/swift-api→Swift）
LightAIP	18080	aip	NLQ 智能查数
LightFoundry	18081	foundry	本体/指标/数据集/管道/血缘
LightApollo	18082	apollo	声明式部署 Hub（控制平面）
LightGotham	18083	gotham	情报分析
LightSwift	18084	swift	星基结算仿真 PoC
Vite 开发	5173	node	仅开发模式

端口约定：勿用 8080（系统 httpd.exe）与 8000。各产品为 server 级单进程部署（无容器/K8s）。

1.1 数据库

优先 PostgreSQL chatbi_action_dev（五产品共用），连接参数 DB_* 环境变量，默认 postgres / ZYCBI2025 / 127.0.0.1 / 5432；
PG 不可用自动降级 SQLite：AIP temp/aip_platform.db、Foundry temp/foundry_platform.db、Apollo temp/apollo_platform.db、Gotham temp/gotham_platform.db（图谱 temp/gotham_graph.json）、Swift temp/swift_platform.db。

降级 SQLite 后 psql 断言（RBAC 赋权/审计验证）不可用；Gotham 重建图谱：删除 temp/gotham_graph.json 后重启。

1.2 V5 新增平台表（运维排查用）

表	用途
scheduler_jobs / scheduler_runs	统一调度器注册表与运行记录
tasks	异步任务五态（queued/running/success/failed/cancelled + progress/result）
cdc_watchers / cdc_events	数据变更捕获 watcher 与事件流水
aie_entities / aie_relations	实体/关系抽取结果
ad_answers / ad_citations	决策证据链答案与引用
anl_conversation_memory	AIP 会话记忆
fd_datasets / fd_dataset_versions、fs_sync_targets / fs_sync_runs、fq_profiles / fq_scores	Foundry 数据集 / 同步 / 质量画像
fn_notebooks / fn_cells、fr_reports / fr_report_runs、ff_projects / ff_matches、fst_rules / fst_deliveries	Notebook / 报表 / Fusion / 流规则
fg_markings / fg_marking_bindings / fus_user_markings、fon_functions	安全标记 / 本体函数
fm_items / fm_installs、fcr_repos / fcr_files / fcr_revisions、fx_search_stats	组件市场 / 代码仓库 / 统一搜索热度
gf_graph_mappings、ga_partitions	Gotham 图谱映射 / 图分区缓存
auth_mfa_secrets	TOTP 双因子密钥

2. 进程启停

2.1 启动

发布包：双击 运行AI商业行动系统.bat（全部进程）；单产品 start-aip/foundry/apollo/gotham/swift.bat；
源码构建：cd /f/chatBI/chatBI_dev/action && go build -o temp/aip_server.exe ./products/aip/cmd（各产品同理）；
embed 单二进制（v5）：scripts/build_embed.sh 三步（npm run build → 拷贝 dist 到 products/foundry/cmd/webdist → go build -tags embed）产出含前端整站的单二进制；默认无 tag 构建走磁盘 web/dist（缺省纯 API 模式）；
发布包构建：scripts/build_release.bat [版本号]（默认 v2026.08.09）——五产品 exe + 前端 + gateway → 拷贝到 release/<版本号>\；
Apollo CLI（cmd/lightapollo）：login / logout / whoami / env / deploy / artifact / pipeline / version，登录态存 ~/.lightapollo/config.yaml。

2.2 检查进程

tasklist | grep -iE "aip|foundry|apollo|gotham|swift|gateway"

2.3 停止进程（必须用 PowerShell）

/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -NoProfile \
  -Command "Stop-Process -Name 'aip_server' -Force"
# 依次：foundry_server / apollo_server / gotham_server / swift_server / gateway

2.4 健康检查

curl -s http://127.0.0.1:18080/health           # zy-action-aip
curl -s http://127.0.0.1:18080/health/live      # 存活探针
curl -s http://127.0.0.1:18080/health/ready     # 就绪探针（database/vector/llm_gateway/disk_space）
curl -s http://127.0.0.1:18081/health           # zy-action-foundry
curl -s http://127.0.0.1:18082/health           # zy-action-apollo
curl -s http://127.0.0.1:18083/health           # zy-action-gotham
curl -s http://127.0.0.1:18084/health           # zy-action-swift
curl -s http://127.0.0.1:18081/metrics          # Foundry Prometheus 指标（v5，无鉴权）

Gotham /ops/health 含图存储/事件总线探测；Apollo 前端 /apollo/ops 运维健康页（四服务健康卡轮询）。

3. 日志运维

3.1 日志位置与滚动

各进程工作目录下 logs/app.log（JSON、lumberjack 滚动 10MB×5×28 天）；LOG_LEVEL 控制等级；
常用排查点：`PostgreSQL unavailable, falling back to SQLite` → PG 未连上已降级；`Demo metadata imported` / `Demo ontology seeded` → 演示数据就绪；bootstrap_summary（v5）→ Foundry 启动自检单条日志（tables_migrated/llm_routes/scheduler_jobs/task_queue 四项）；崩溃定位 tail -50 logs/app.log。

3.2 可观测性：Prometheus 指标（v5）

Foundry 与 AIP 均暴露轻量 Prometheus 文本格式 /metrics（无鉴权，生产建议网关层限制）。Foundry 侧 9 组指标：

指标名	类型	含义
foundry_uptime_seconds	gauge	进程运行时长
http_requests_total	counter	HTTP 请求数（method/path/status，path 取 gin 模板路径聚合）
http_request_duration_ms_sum/count	counter	请求耗时累计（rate 比值得平均时延）
foundry_llm_circuit_open_total	counter	Provider 熔断打开累计
foundry_llm_circuit_state	gauge	实时熔断状态（closed=1/half_open=2/open=3）
foundry_llm_gateway_calls_total	counter	LLM 网关调用（聚合 llm_call_logs，result=success/error/degraded，全平台口径）
foundry_task_queue_depth	gauge	异步任务队列深度（tasks 表 queued 计数）
foundry_scheduler_runs_total	counter	调度运行计数（scheduler_runs 按 job×status）

运维接入：Prometheus scrape_configs 指向 http://<foundry>:18081/metrics（建议 15s）；告警示例：foundry_llm_circuit_state{provider="qwen"} == 3 持续 1m → 熔断告警；foundry_task_queue_depth > 100 持续 5m → 任务堆积告警。AIP 侧为同款 aip_ 前缀（跨产品大盘合并需 label 区分）。

3.3 审计日志

event_type	触发
DEPLOYMENT_SYNC	部署推进至 synced
DRIFT_DETECTED	漂移检测发现不一致
DRIFT_RECONCILE	收敛完成
DEPLOYMENT_TIMEOUT	离线部署超时（5min + Agent 失联）

PSQL="/f/PostgreSQL/17/bin/psql.exe -h 127.0.0.1 -U postgres -d chatbi_action_dev"
export PGPASSWORD=ZYCBI2025
$PSQL -c "SELECT event_type, result, ref_id, created_at FROM audit_log WHERE event_type LIKE 'DRIFT_%' ORDER BY created_at DESC;"

审计为异步落库（~秒级）。Apollo 另有 HTTP 全量审计表 apollo_audit_logs（脱敏 + >2KB 截断）。v5 审计归档：audit:archive 调度任务每天凌晨 3 点归档超 90 天记录，GET|PUT /api/v1/audit/archive-config（AIP）可调。

4. LightApollo：GitOps 与声明式部署

4.1 期望状态声明

入口：Apollo ▾ → 部署总览 /apollo。YAML 描述 app/version/name/channel/components[]/policy。

app: rollout-app
version: 1.0.0
name: rollout-app-v1
channel: stable
components:
  - name: frontend
    kind: binary
    version: "1.0.0"
    source: {type: artifact, ref: bundle/frontend.bin}
    depends_on: [backend]
    probes:
      readiness: {type: tcp, url: "127.0.0.1:8080", interval_s: 1, failure_threshold: 3}
  - name: backend
    kind: binary
    version: "1.0.0"
    source: {type: artifact, ref: bundle/backend.bin}
policy:
  require_guomi_signature: false
  ignore_paths:
    - /components/*/runtime/*

操作	API	预期
创建	POST /api/v1/desired-states（application/yaml）	状态 draft；循环依赖拒绝 400 DESIRED_STATE_DAG_CYCLE
审批	POST /api/v1/desired-states/:id/approve\|reject	审批流（G15），未批准则 Spoke 拉取/激活被约束
激活	POST /api/v1/desired-states/:id/activate	→ active（激活前过 SecurityGate 门禁）
回滚	POST /api/v1/desired-states/:id/rollback（target_desired_state_id）	生成 rollback 草稿（rollback_of 指向目标、bundle_version=max+1）

单调版本约束：同 app 重复 apply 同配置 → 409 DESIRED_STATE_CONFLICT；新名称 bundle_version 单调递增。组件类型：binary / config / llm_route / eval_set / ontology_yaml（跨产品分发载体）。

4.2 部署推进（Rollout：DAG + 就绪门控）

入口：/apollo/deployments。步骤：start（POST /api/v1/deployments/start）→ 查看组件（level-0 先 deploying）→ advance（POST /api/v1/deployments/:id/advance）→ 全部 ready 后 synced。

实测（frontend 依赖 backend）：start 后 backend=deploying、frontend=pending；advance(backend ready) → next_batch=[frontend]、ready_count=1；advance(frontend ready) → synced（ready=2/2）。

超时/就绪失败按 readiness_timeout_sec / failure_threshold；auto_rollback=true 自动回滚；同 Agent 进行中部署 409 DEPLOYMENT_CONFLICT。状态机：pending / deploying / synced / drifting / degraded / failed。

4.3 漂移检测与收敛

操作	API	说明
检测	POST /api/v1/drift/check	返回 has_drift + diff，部署标记 drifting
事件	GET /api/v1/drift/events?desired_state_id=&agent_name=	漂移事件列表
收敛	POST /api/v1/drift/:event_id/reconcile	→ synced，落 DRIFT_RECONCILE 审计
自动调和	drift_policy=auto_fix	经 apolloDriftAutoFix，防循环（上限 3 + 防抖 5min）
手动 sync	POST /api/v1/deployments/:id/sync	F2：清退避置回 pending，Spoke 下轮强制重调和

要点：JSON Patch（RFC 6902）路径级 diff；ignore_paths 通配（/components/*/digest、/components/**/readiness）。

4.4 回滚

对 active 期望状态点「回滚」→ 生成新 draft（rollback_of 指向目标）→ 激活 → 重新部署。回滚不走 SecurityGate 门禁（自愈应急恢复）。

4.5 Bundle 构建与验签（SM3 + SM2）

入口：/apollo/bundles。构建 POST /api/v1/bundles（multipart）→ digest(SM3) + SM2 签名；下载 GET /api/v1/bundles/:id/download（zip：manifest.json + digest.sig + files/）；验签 POST /api/v1/bundles/:id/verify（files_ok/digest_ok/signature_ok/trusted）；生命周期清理 POST /api/v1/bundles/cleanup/run。

验签四要素（G1）全通过才 trusted：篡改文件 → files_ok=false、digest_ok=false；签名者不在白名单 → signature_ok=false、trusted=false（VERIFY_SIGNER_NOT_TRUSTED）。签名者管理 GET/POST /api/v1/signers、POST /api/v1/signers/:id/enable|disable。

4.6 Spoke Agent 注册与心跳

入口：/apollo/agents。Spoke 纯 Pull（出向拉取/上报，无入站端口）。

操作	API	认证	说明
拉取	GET /api/v1/agent/pull?agent=<name>	无/可选 Token	has_update + desired_state + bundle_digest
上报	POST /api/v1/agent/report	无/可选 Token	actual_snapshot + component_states + mem_mb/cpu
在线列表	GET /api/v1/agents	JWT	agent_name/status/last_seen
引导	POST /api/v1/environments/:id/agents	JWT	Bootstrap Token（SHA256 哈希存储，明文仅返回一次）

心跳状态机：90s → degraded / 300s → offline（30s 扫描）。ProcManager 崩溃自愈指数退避（5s×2 封顶 5min），达 3 次/组件 → degraded 并告警。

演示 Poller 仅拉取/上报，不真实部署进程（ProcManager 未挂载时不应用）。

5. LightApollo：配置/监控/告警/自愈/安全

5.1 配置管理

入口：/apollo/configs。模板 GET/POST /api/v1/projects/:id/config-templates（raw_yaml/kustomize/helm）；渲染/对比 POST /api/v1/config-templates/:id/render|diff（Base+Overlay 深度合并 + 变量替换 + schema 校验）；密钥 GET/POST /api/v1/projects/:id/secrets（AES-256-GCM，密文 AES256:<iv>:<ct>）；导出 sealed-yaml GET /api/v1/secrets/:id/sealed-yaml、轮换 POST /api/v1/secrets/:id/rotate、解密 POST /api/v1/secrets/:id/decrypt。

5.2 监控可观测

监控配置 GET/PUT /api/v1/projects/:id/monitoring-config；健康检查 GET/POST /api/v1/projects/:id/health-checks（HTTP/TCP/exec/file，30s 全量调度，连续失败默认 3 判 unhealthy）；健康汇总 GET /api/v1/projects/:id/health-status；仪表盘 GET/POST /api/v1/projects/:id/dashboards（6 类内置模板）。部署↔监控打点（G18）。

5.3 告警与自愈

告警规则 GET/POST /api/v1/projects/:id/alert-rules（health_check/event 触发，阈值比较，15s 评估）；事件单 GET /api/v1/projects/:id/incidents、/incidents/:id/acknowledge|investigate|resolve；通知渠道 GET/POST /api/v1/projects/:id/notification-channels——仅 webhook 真实发送，email/dingtalk/wecom 为日志占位；自愈策略 GET/POST /api/v1/projects/:id/healing-policies（restart/rollback/scale_*/clean_disk）；自愈审批 POST /api/v1/healing-history/:id/approve|deny；静默 GET/POST /api/v1/projects/:id/silences；汇总 GET /api/v1/projects/:id/alert-summary。部署失败衔接（G12）：失败/自动回滚直写 alert_events + incidents。

5.4 安全合规与部署左移门禁

SBOM POST /api/v1/artifacts/:id/sbom（SPDX 2.3/CycloneDX 1.5）；漏洞扫描 POST /api/v1/artifacts/:id/scan、GET /api/v1/artifacts/:id/vulnerabilities（内置模拟扫描器：四规则 + 内置漏洞库）；策略引擎 GET/POST /api/v1/projects/:id/security-policies（6 类规则 + 5 模板，deny>warn>allow）；部署门禁 POST /api/v1/security-gate/evaluate（deny → 保持 draft + sync failed）；合规报告 GET /api/v1/projects/:id/compliance-report。

6. LightSwift：部署运维与授权自检（v5）

Swift 为 P5 数据导入流水线（先仿真）：SWIFT+卫星金融结算、星上结算、国密全链路。端口 18084（SWIFT_PORT 优先，其次 config）。

6.1 启动与优雅退出

main：LoadConfig（fallback）→ Bootstrap（PG→SQLite）→ NewServer → StartLicenseWatcher 授权自检。退出双路：系统信号或 POST /api/v1/admin/shutdown → httpServer.Shutdown（5s）。

6.2 授权自检（License Watch）

周期校验：WatchPeriodic 启动立即校验 + 每 30 分钟在线校验（LicenseCheckInterval=30min）；交 ShutdownScheduler 幂等评估；
关停语义：授权不满足 → 到点 handleLicenseShutdown → graceful → main select → httpServer.Shutdown，优雅退出本产品、不影响其它产品；
AUTH_KEY：ResolveAuthKey 三级兜底 DB→env→config.yaml；在线校验 nonce+crypt_data（与 AIP 授权同协议，参考 drama_studio 授权服务器）。

6.3 授权/运维端点

端点	鉴权	说明
GET /api/v1/license/info	protected	机器码+有效期仅展示；force=1 强制重校验，否则 TTL 缓存
PUT /api/v1/license/auth-key	内联 admin JWT（共享 SECRET_KEY）	写 AUTH_KEY，成功清空授权缓存
POST /api/v1/admin/shutdown	公开路由+内联 admin JWT	触发本产品优雅退出

子命令：run / service / backup / health。

7. 数据库运维

7.1 PostgreSQL 初始化

psql -U postgres -c "CREATE DATABASE chatbi_action_dev;"

7.2 重置/重建演示数据

产品	方式
AIP	重启进程（演示 SQLite 每次启动重建 + 重导元数据）
Foundry	重启进程（demo 数据源重建 + 本体/指标幂等 seed）
Apollo	重启进程（期望状态/签名者/渠道/策略幂等 seed）
Gotham	重启进程（幂等 seed；删 temp/gotham_graph.json 强制重建图谱）
Swift	重启进程（账号/报文/链路/结算演示数据 seed）

7.3 审计与 RBAC 表（运维用）

$PSQL -c "\dt"
$PSQL -c "SELECT event_type,result,count(*) FROM audit_log GROUP BY 1,2 ORDER BY 3 DESC;"
$PSQL -c "SELECT u.username, r.role_name FROM users u JOIN user_roles ur ON ur.user_id=u.id JOIN roles r ON r.id=ur.role_id;"
$PSQL -c "SELECT app, COUNT(*) FROM llm_call_logs GROUP BY 1;"
$PSQL -c "SELECT job_name, status, COUNT(*) FROM scheduler_runs GROUP BY 1,2;"   # 调度运行统计（v5）

8. 各产品部署边界（如实标注）

产品	部署边界
AIP	单机原生；LLM 依赖外部（deepseek→qwen→local_rule 降级链）；HTTP 无 TLS；API 层无限流；默认无 Docker/K8s（Dockerfile.aip 已交付，多阶段 + distroless）
Foundry	单进程；v5 起数据源自管理（不再依赖 AIP 后端）；MLOps 只推理不训练；三语言 SDK 未实现；支持 embed 单二进制（-tags embed）与 Dockerfile.foundry 镜像部署
Apollo	控制平面 18082；Git 本地目录模拟（非真实 Git 平台）；扫描器内置模拟；通知渠道占位；监控自研探针；单机 HA 无
Gotham	单进程；图存储 disk（内存邻接表 + JSON 落盘）/ Neo4j 可选；图谱域分析 admin-only；性能基准待测
Swift	仿真域 PoC（星座/链路/结算为模拟数据）；真实卫星/真实银行清算不在本轮；真实 HSM 等 ○规划中；内建授权自检（30min 周期）

9. 常见故障排查

故障	排查步骤
一键启动后浏览器打不开	检查 gateway 是否占用 80 端口；tasklist 确认进程在跑；看 logs/app.log
AIP NLQ 无响应/报 LLM 错误	确认 .env 注入 LLM Key；LLM 网关降级链；/api/v1/llm/routes 查路由健康
服务降级到 SQLite 但想要 PG	设置 DB_USER/DB_PASSWORD/DB_HOST/DB_PORT 并确认 chatbi_action_dev 可 ping
/metrics 抓不到指标	确认端口 18081 可达；/metrics 无鉴权（生产建议网关层限制）；foundry_llm_gateway_calls_total 在无 llm_call_logs 表时仅打 Warn 日志并跳过该组（纯日志噪音）
漂移持续 detected	检查 ignore_paths 覆盖运行时字段；Agent 是否仍在上报（last_seen）；auto_fix 防循环上限
部署卡 pending/deploying	检查 Agent 心跳（90s/300s）；离线部署超时（F7）；就绪门控失败次数
回滚草稿无法部署	回滚生成 draft，需先激活；G15 审批流未批准也会被约束
Agent 列表状态非 online	手动调 POST /api/v1/agent/report 验证链路；确认 Bootstrap Token 引导完成
bundle 验签不通过	确认签名者已入白名单（trusted_signers）；确认篡改文件后 digest/files 校验失败原因
冒烟 psql 断言失败	确认连接的是 chatbi_action_dev（勿错连 chatbi_forge_dev）
端口被占用	改用其他端口（勿用 8080/8000）；停止进程必须用 PowerShell Stop-Process
各产品进程被 AIP 自动结束	AIP 授权（AUTH_KEY）过期按宽限档/硬关档自动关停：到点由 AIP 结束 foundry/apollo/gotham/swift 进程后退出（保留 gateway 与前端），属授权机制非故障；GET /api/v1/license/info 查看 shutdown_scheduled/deadline/tier/reason，续期后自动恢复
Swift 进程被自动关停	Swift 内建授权自检：授权不满足每 30 分钟校验后优雅退出本产品（不影响其它产品）；GET /api/v1/license/info（Swift 端口）查状态，PUT /api/v1/license/auth-key 更新密钥
工作流飞书/邮件通知失败	检查 FEISHU_APP_ID/FEISHU_APP_SECRET（GET /api/v1/feishu/status）与 EMAIL_*（GET /api/v1/email/status）配置是否齐全；未配置而使用 channel=feishu/email 会让节点直接失败；用 POST /api/v1/email/test 验证 SMTP 连通性
embed 二进制打不开前端	确认构建走 build_embed.sh / Docker（go build -tags embed）；默认无 tag 构建走磁盘 web/dist，dist 缺失时回退纯 API 模式（行为不变，属预期）