ZY Action Platform 管理员使用说明

适用对象：平台管理员 · 覆盖产品：P1 LightAIP / P2 LightFoundry / P3 LightApollo / P4 LightGotham / P5 LightSwift · v5 对齐 wiki/docs 系列文档与 V5 七阶段升级 · 端口 18080-18084 + 网关 80，admin/admin1

1. 系统启动与访问入口

1.1 一键启动（推荐）

在发布目录（action/release/v2026.08.11/）双击 运行AI商业行动系统.bat：

1. 自动注入 .env 中的 LLM Key（DeepSeek/DashScope/Anthropic/OpenAI）；
2. 拉起进程：aip.exe→AIP(18080)、foundry.exe→Foundry(18081)、apollo.exe→Apollo(18082)、gotham.exe→Gotham(18083)、swift.exe→Swift(18084)、gateway.exe→网关(80)；
3. 自动打开 http://127.0.0.1/，按任意键停止全部进程。

1.2 端口与访问方式

网关前缀 `/api/*`→Foundry、`/apollo-api/*`→Apollo、`/aip-api/*`→AIP、`/gotham-api/*`→Gotham、`/swift-api/*`→Swift（前缀重写为 /api），其余 SPA fallback。

1.3 数据库与日志

• 优先 PostgreSQL，库名固定 chatbi_action_dev（五产品共用），连接参数 DB_* 环境变量；
• 降级 SQLite 平台库：AIP temp/aip_platform.db、Foundry temp/foundry_platform.db、Apollo temp/apollo_platform.db、Gotham temp/gotham_platform.db（图谱 JSON temp/gotham_graph.json）、Swift temp/swift_platform.db；
• 日志：各进程工作目录下 logs/app.log（JSON、lumberjack 滚动 10MB×5×28 天）。

2. 前端登录

2.1 默认管理员账号

2.2 登录步骤

1. 打开 http://127.0.0.1/ → 自动跳转 /login；
2. 输入用户名/密码 → 登录；
3. 成功返回 JWT（存 aip_token），自动落地到 Foundry 本体工作台 /foundry。

Apollo 独立登录页 + JWT/API-Key 双通道（lap_ 前缀）；Swift 内嵌登录（admin/admin1）。

2.3 双因子认证（TOTP MFA，v5）

• 平台支持 TOTP 动态口令双因子登录校验（RFC 6238，hmac-sha1 + Base32，30 秒窗口 ±1）；
• 表 auth_mfa_secrets（新表放 platform/auth 模块内，各产品 bootstrap 自动迁移）；
• 流程：setup（生成密钥与二维码）→ verify-enable（输入当前口令激活）→ 登录时要求 totp_code（未输口令返回 MFA_REQUIRED 错误码）→ disable 关闭；
• 当前应用于登录路径；其余敏感操作未强制二次验证（已知限制）。

2.4 导航结构

3. 用户与角色管理（RBAC）

3.1 账号体系

用户 users（UUID 主键、username 唯一、bcrypt 哈希）、角色 roles、关联 user_roles、权限 role_permissions、行级安全 row_level_security_policies 与 role_rls_policies。v5 新增：fg_markings/fg_marking_bindings/fus_user_markings（安全标记与授权矩阵）、auth_mfa_secrets（TOTP 双因子密钥）。

3.2 用户注册/登录

curl -s -X POST http://127.0.0.1:18081/api/v1/auth/register -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"pass123"}'
curl -s -X POST http://127.0.0.1:18081/api/v1/auth/login -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"pass123"}'

3.3 角色授权（admin 角色）

PSQL="/f/PostgreSQL/17/bin/psql.exe -h 127.0.0.1 -U postgres -d chatbi_action_dev"
export PGPASSWORD=ZYCBI2025
# 1) 确保 admin 角色存在
$PSQL -c "INSERT INTO roles(role_name) SELECT 'admin' WHERE NOT EXISTS(SELECT 1 FROM roles WHERE role_name='admin');"
# 2) 绑定用户到 admin 角色（USER_ID 为 users 表 UUID）
$PSQL -c "INSERT INTO user_roles(user_id, role_id) SELECT '<USER_ID>', r.id FROM roles r WHERE r.role_name='admin';"
# 3) 验证
$PSQL -t -c "SELECT count(*) FROM user_roles ur JOIN roles r ON r.id=ur.role_id WHERE ur.user_id='<USER_ID>' AND r.role_name='admin';"

admin 角色作用：Foundry Action 写路径逐动作授权放行；Gotham ABAC 基础门全动作放行（非 admin 高危写默认拒绝，图分析与图谱域分析仅 admin）；Apollo 内置 5 角色权限点引擎；语义查询注入 RLS/CLS（v5 起 AIP NLQ 主链路同样注入，失败拒绝执行）。

3.4 安全标记（Markings，v5）

入口：Foundry 侧边栏「数据打标」/foundry/markings，API：/api/v1/markings + /api/v1/markings/bindings + /api/v1/markings/user-markings。支持对象/列级安全标记定义、绑定（组合唯一）与用户授权矩阵；隐藏列自动叠加至列级安全生效（任一来源隐藏即隐藏，NULL AS col）；管理语义：标记 CRUD / 绑定目标 / 授权与撤销，前端授权矩阵可视化。

4. 审计日志查看

查询方式一（AIP 接口）：GET http://127.0.0.1:18080/api/v1/audit/logs?limit=50&offset=0

查询方式二（直查库，各产品通用）：$PSQL -c "SELECT event_type, ref_id, result, user_id, created_at FROM audit_log ORDER BY created_at DESC LIMIT 50;"

4.3 审计归档（v5）

平台内置归档任务：调度器 audit:archive，0 3 * * *（每天凌晨 3 点）归档超 90 天（settings 可调）的审计记录；REST GET|PUT /api/v1/audit/archive-config（AIP 挂载）查看/配置归档策略，AIP 审计页带归档开关。归档后旧记录不再出现在常规查询（如实标注：物理保留，未做压缩/导出）。

5. LightAIP 管理侧操作（18080）

5.1 数据源管理

入口：顶部导航「数据源管理」/datasources。

内置演示数据源：aip_demo_warehouse（SQLite：orders/customers/products，启动重建+重导元数据）。

5.2 异步任务与统一调度（v5）

平台底座提供统一调度器 + 异步任务系统（platform/scheduler + platform/task），长耗时操作全部任务化，前端实时查看进度：

5.3 管理后台 18+ 模块

覆盖：用户/角色/审计/AI 决策审计/设置/深度权限/LLM 网关/Prompt/工具/RAG/本体/安全/评测/监控/工作流/Agent/飞书设置/邮件设置。

5.4 通知中心（v5）

平台通知中心（platform/notify）：Hub/Channel/Send/Channels，统一站内通知与多渠道消息发送管理。API：GET /api/v1/notify/channels、POST /api/v1/notify/send（AIP/Foundry 均挂载）。内置 emailChannel（未配置明确报错）；AIP 注册 feishu 渠道（延迟解析），Foundry 无飞书引擎运行时降级标注。

5.5 飞书机器人配置与主动推送

入口：管理后台「飞书设置」/admin/feishu。

• 配置项（config.yaml feishu: 节 + FEISHU_* 环境变量 + system_settings）：app_id / app_secret / enable_feishu_card / allow_from / allow_chat / default_channel（copilot|nlq）。
• 配置了 app_id+app_secret 且未显式禁用时默认启用机器人（WebSocket 长连接）。
• 用途：Copilot 对话与 NLQ 查数经飞书交互；工作流 send_notification 节点 channel=feishu 按 recipients（open_id）推送私聊。
• 主动推送需用户先与机器人发起过会话（feishu_contacts 登记 open_id↔chat_id）。

5.6 邮件服务配置（SMTP 通知渠道）

入口：管理后台「邮件设置」/admin/email。

• 配置项（config.yaml email: 节 + EMAIL_* 环境变量 + system_settings，DB 覆盖优先）：server / port（默认 465）/ username / password / from / from_name / starttls / ssl。
• 有 server+username+password 且未显式禁用时默认启用；支持 SSL(465) / STARTTLS(25·587) / 明文三种模式。
• 用途：工作流 send_notification 节点 channel=email 按 recipients（邮箱）发 SMTP 邮件。

5.7 授权过期自动关闭（license 关停与自检）

• AIP 授权（AUTH_KEY）过期后自动关停：过期<30 天或网络校验失败按宽限档（6h+随机 0~2h）；未注册或过期 ≥30 天按硬关档（20min+随机 0~10min）。
• 到点由 AIP 结束 foundry/apollo/gotham/swift 进程（按进程名+bin 目录过滤防误杀）后退出，保留 gateway 与前端。
• 前端全局弹窗倒计时提醒；查询状态 GET /api/v1/license/info（force=1 强制在线重校验，否则 TTL 缓存）；更新密钥 PUT /api/v1/license/auth-key（admin）。
• Swift 亦内建授权自检：启动立即校验 + 每 30 分钟在线校验，不满足优雅退出本产品、不影响其它产品（详见《运维工程师使用说明》）。
• 授权周期自检需完成授权配置后方可生效（已知限制）；AUTH_KEY 仅在 AIP 配置与校验。

6. LightGotham 管理侧操作（18083）

6.1 访问控制策略（ABAC）

入口：Gotham ▾ → 访问控制 /gotham/access。

6.2 内置策略

演示数据中 graph:org:xuanwu（玄武集团）为 secret，分析师读取将被拒绝。

6.3 评估 trace 验证

# internal → allow
curl -s -X POST http://127.0.0.1:18083/api/v1/access-policies/evaluate -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"analyst1","roles":["analyst"],"user_attrs":{"role":"analyst"},"resource_attrs":{"classification":"internal"},"action":"read"}'
# secret → deny（一票否决）
curl -s -X POST http://127.0.0.1:18083/api/v1/access-policies/evaluate -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"analyst1","roles":["analyst"],"user_attrs":{"role":"analyst"},"resource_attrs":{"classification":"secret"},"action":"read"}'

6.4 图谱域管理（v5，admin-only）

7. LightApollo 管理侧操作（18082）

7.1 发布渠道与策略

渠道：GET/POST /api/v1/channels、PUT/DELETE /api/v1/channels/:id、POST /api/v1/channels/:id/set-desired-state。内置 stable 指向 demo-app。期望状态审批流（G15）：POST /desired-states/:id/approve|reject。

策略：GET/POST /api/v1/policies、PUT/DELETE /api/v1/policies/:id；rules 含 auto_rollback / max_concurrent / readiness_timeout_sec / reconcile_backoff。内置 default（auto_rollback=true）。

7.2 签名者白名单（G1 信任锚）

GET/POST /api/v1/signers、PUT/DELETE /api/v1/signers/:id、POST /api/v1/signers/:id/enable|disable。内置 demo-signer（首次构建 bundle 自动升级为真实 SM2 密钥指纹）。bundle 四要素：SM3 校验和 + SM2 签名 + 不可变 digest + 签名者白名单。

7.3 Spoke Agent 与环境管理

环境：GET/POST /api/v1/projects/:id/environments（kubernetes/vm_cluster/bare_metal/edge 四类四态）；Agent 引导 POST /api/v1/environments/:id/agents（Bootstrap Token SHA256 哈希，明文仅返回一次）；拉取 GET /api/v1/agent/pull（无需认证，出向）；上报 POST /api/v1/agent/report。心跳 90s→degraded / 300s→offline。手动 sync：POST /deployments/:id/sync（F2）。

7.4 监控/告警/自愈/配置/安全

• 监控：GET/POST /api/v1/projects/:id/health-checks、GET /api/v1/projects/:id/health-status（HTTP/TCP/exec/file 探针，30s 调度）；
• 告警：GET/POST /api/v1/projects/:id/alert-rules、/incidents/:id/acknowledge|investigate|resolve（15s 评估）；
• 自愈：GET/POST /api/v1/projects/:id/healing-policies、/healing-history/:id/approve|deny（restart/rollback/scale_*/clean_disk + 审批流）；
• 配置：GET/POST /api/v1/projects/:id/config-templates、/secrets/:id/sealed-yaml|rotate（Base+Overlay + AES-256-GCM Sealed-Secret）；
• 安全：POST /api/v1/artifacts/:id/sbom|scan、GET /api/v1/projects/:id/compliance-report（SBOM + 内置扫描 + 策略引擎 + SecurityGate 部署左移门禁）。

8. LightFoundry 管理侧操作（18081）

8.1 数据源接入（自管理，v5）

v5 起 Foundry 数据源独立自管理（不再依赖 AIP 后端）：入口侧边栏「数据源」/foundry/datasources，接口 /api/v1/datasources（Foundry 侧注册）。导入元数据任务化（type=foundry_import_metadata，快路径 + 202 轮询对齐 AIP 模式）。内置演示 foundry_demo_warehouse（SQLite：customers/orders/products）。接入新数据源：注册连接 → 导入元数据 → 本体工作台创建对象（data_source_id + base_table + pk_column）。

8.2 数据集 / 同步 / 质量画像管理（v5）

8.3 对象/权限管理

• 对象列表 GET /api/v1/ontology/objects；详情 GET /api/v1/ontology/objects/:id；
• 删除被引用对象会拒绝；影响分析 POST /api/v1/ontology/objects/:id/impact；
• Action 写路径按 RBAC 授权，执行 POST /api/v1/ontology/actions/:name/execute（幂等键 + 乐观锁，冲突 409 ACTION_CONFLICT）；版本审批 POST /api/v1/ontology/objects/:id/versions/:vid/approve|reject；
• v5 写入前校验：Action.ValidationRules 表达式条件，失败聚合提示且失败即阻断（默认安全）；
• API Key：GET/POST /api/v1/api-keys、POST /api/v1/api-keys/revoke（lfk_ 前缀）；审计：GET /api/v1/audit/events 与 summary|export|archive。

8.4 语义互操作管理（v5）

8.5 生态与工程管理（v5）

8.6 数据质量与血缘

质量规则 GET/POST /api/v1/quality/rules；问题清单 GET /api/v1/quality/issues（acknowledge/fix，error 级阻断目标对象同步）；血缘 GET /api/v1/lineage?type=object&id=<name>&direction=downstream&depth=2。任务端点前缀 /api/v1/system/tasks（gin 通配符冲突规避，勿改回 /tasks）；契约测试 TestOpenAPIContractRoutes 自动对拍，新增端点必须同步补 openapi.go。

9. 常见问题