# 中控 AI 与部署密钥配置

本文档说明:**长期部署密钥**(一次生成,不轮换),**SSO 临时链接**(保持不动),以及 **AI 配置**(中控统一维护并同步三所).

---

## 1. 三类「密钥」分工

| 类型 | 变量 / 机制 | 谁维护 | 是否自动过期 |
|------|-------------|--------|--------------|
| **长期通信密钥** | `HUB_BRIDGE_TOKEN` | 部署脚本首次写入四份 `.env` | 否,不轮换 |
| **实例 Session 签名** | `FLASK_SECRET_KEY` | 部署脚本首次写入三实例 | 否 |
| **中控 Session 签名** | `HUB_SESSION_SECRET` | 部署脚本首次写入中控 | 否 |
| **SSO 开门链接** | `/hub-sso?token=...` | 中控每次点「打开实例」签发 | 默认 2h + 单次 |
| **AI 配置** | `OPENAI_*`,`AI_*` 等 | 中控系统设置 → AI 配置 | 否 |

**SSO 保持不动**:仍为随机 nonce,默认 `HUB_SSO_TTL_SEC=7200`,成功登录一次后链接作废.长期 `HUB_BRIDGE_TOKEN` 只用于签名,不会每 2 小时变化.

---

## 2. 首次部署自动生成

`bash deploy/setup_env.sh` 在复制 `.env.example` 后自动执行:

```bash
python3 scripts/bootstrap_deploy_secrets.py
```

| 写入项 | 位置 | 规则 |
|--------|------|------|
| `HUB_BRIDGE_TOKEN` | 中控 + 三实例(同值) | 仅空或占位符时写入 |
| `FLASK_SECRET_KEY` | 三实例(同值) | 仅空或占位符时写入 |
| `HUB_SESSION_SECRET` | 中控 | 仅空时写入 |
| `HUB_USERNAME` / `HUB_PASSWORD` | 中控 | 默认 admin / admin123(仅空时) |
| `APP_USERNAME` / `APP_PASSWORD` | 三实例 | 默认 admin / admin123(仅空时) |

**已有非空生产值不会被覆盖**(一次生成,不轮换).

子代理 `agent.py` 优先读取 `HUB_BRIDGE_TOKEN` 作为 `X-Control-Token` 校验;独立配置 `CONTROL_TOKEN` 已废弃.

---

## 3. 中控系统设置 → AI 配置

路径:**中控 Web → 系统设置 → AI 配置** Tab.

### 3.1 可配置项

| 中文名 | 环境变量 |
|--------|----------|
| AI 提供方 | `AI_PROVIDER` |
| API 地址 | `OPENAI_API_BASE` |
| API 密钥 | `OPENAI_API_KEY`(掩码,留空不修改) |
| 云端模型 | `OPENAI_MODEL` |
| Ollama 地址 | `OLLAMA_API` |
| Ollama 模型 | `AI_MODEL` |
| 请求超时(秒) | `AI_TIMEOUT_SECONDS` |

### 3.2 保存行为

1. 写入 `manual_trading_hub/.env`
2. **强制同步** 至 `crypto_monitor_okx/binance/gate/.env` 相同键
3. 自动 `pm2 restart` 中控 + 三实例(`--update-env`)

### 3.3 API(需已登录中控)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/settings/ai-env` | 读取字段与三所同步状态 |
| POST | `/api/settings/ai-env` | body: `{ "values": {...}, "restart": true }` |

实现:`lib/env/shared_env_lib.py`,`manual_trading_hub/hub_env_lib.py`.

---

## 4. 实例 env 配置页变更

三所 **env 配置** 页已 **移除「AI 复盘」卡片**.交易所 API,企业微信,交易执行等仍各所自配.

实例侧若通过 API 提交已移除的 AI 键,会被白名单过滤,不会写入.

---

## 5. 与系统设置 / env 页对照

| 能力 | 实例 env | 实例系统设置 | 中控系统设置 |
|------|----------|--------------|--------------|
| 交易所 API | ✅ | ❌ | ❌ |
| OpenAI / AI | ❌ | ❌ | ✅(同步三所) |
| 实例登录密码 | ❌ | ✅ | ❌ |
| 中控登录密码 | ❌ | ❌ | ✅ |
| Bridge / Flask 长期密钥 | ❌(自动) | ❌ | ❌(自动) |
| SSO 链接 | — | — | 每次打开实例自动签发 |

---

## 6. 运维提示

- 修改 AI 后若未自动重启成功,手动:`pm2 restart manual-trading-hub crypto_okx crypto_binance crypto_gate --update-env`
- 三所 AI 不一致时,中控 AI 配置页会提示「未完全同步」;点 **保存并同步** 即可对齐
- 备份包可选包含各 `.env`(中控设置 → 备份恢复)

相关文档:[env配置说明.md](./env配置说明.md),[系统设置说明.md](./系统设置说明.md),[manual_trading_hub/局域网与反代部署说明.md](../manual_trading_hub/局域网与反代部署说明.md)(SSO 2h 说明)