# 部署指南（独立部署 / 单机演示）

一条命令拉起整套 sundynix-agentix（应用 5 服务 + 基建）。适用于**演示**与**客户独立部署**。
集群高可用（多副本 / NATS 集群 / 数据库主从）是用户量上来后的事，不在本指南范围。

## 前置
- Docker 24+ 与 Docker Compose v2
- 约 8GB 内存、10GB 磁盘（Milvus/Neo4j 较吃资源）

## 三步上手

```bash
# 1) 生成配置
cp .env.example .env

# 2) 填密钥（必填四项 + 管理员）
#    主加密密钥 / JWT 密钥：
openssl rand -base64 32   # 填入 SUNDYNIX_SECRET_KEY
openssl rand -base64 32   # 填入 JWT_SECRET
#    数据库密码：
openssl rand -base64 24   # 填入 POSTGRES_PASSWORD（勿含 @ : /）
openssl rand -base64 24   # 填入 NEO4J_PASSWORD
#    ADMIN_USER_IDS 先留空（见下「首次管理员」）

# 3) 起服务（首次会构建镜像，约几分钟）
docker compose -f docker-compose.prod.yml up -d --build
```

起来后：
- 控制台： http://<服务器IP>:80
- 网关 API： http://<服务器IP>:8080 （桌面端连这里）
- 链路追踪 UI（可选）： http://<服务器IP>:16686

## 首次管理员
生产模式下 `/admin` 仅 `ADMIN_USER_IDS` 白名单可进。首次：
1. 打开控制台注册第一个账号；
2. 取该账号的用户 id（注册响应里有，或 `GET /api/v1/auth/me`）；
3. 填进 `.env` 的 `ADMIN_USER_IDS`，`docker compose -f docker-compose.prod.yml up -d gateway` 重启网关。

## 配置模型（部署后在控制台做）
LLM 模型 API key **不放 .env**，登录控制台 →「模型管理」配置：
- 对话模型（chat）：在线 API（OpenAI 兼容，如 DeepSeek）或本地 vLLM/Ollama
- 向量模型（embedding）：RAG 用
平台会用 `SUNDYNIX_SECRET_KEY` 把这些 key AES 加密后存库，不落明文。

## 两类密钥（重要）
| 类别 | 放哪 | 例子 |
|---|---|---|
| 引导密钥 / 基建凭据 | `.env`（部署时填一次） | `SUNDYNIX_SECRET_KEY`、`JWT_SECRET`、库密码 |
| 业务模型 key | 控制台（运行时配，加密存库） | DeepSeek / Qwen / embedding 的 api_key |
`SUNDYNIX_SECRET_KEY` 是前者加密后者的主密钥，**务必备份且不可泄露**；丢失=已存模型 key 全部失效。

## 备份 / 恢复
见 `scripts/backup.sh` 与 `scripts/restore.sh`（备份 PG / Neo4j / Milvus / MinIO 数据卷）。
建议 cron 每日跑 `backup.sh`，产物存异机。

## 安全建议（对外开放时）
- 生产把 `CORS_ALLOW_ORIGIN` 设为具体域名，别留 `*`。
- 基建端口（PG/Redis/NATS/Milvus/Neo4j/MinIO）默认**不对宿主暴露**，仅 compose 内网；勿手动开放。
- 对外建议在 admin 容器前再加一层 TLS 反代（Caddy/Nginx），或用云 LB 终止 HTTPS。
- `SUNDYNIX_SECRET_KEY`/`JWT_SECRET` 用 `openssl rand` 生成的强随机值，切勿用示例值。

## 运维常用
```bash
docker compose -f docker-compose.prod.yml ps          # 状态
docker compose -f docker-compose.prod.yml logs -f gateway
docker compose -f docker-compose.prod.yml down         # 停（保留数据卷）
docker compose -f docker-compose.prod.yml up -d --build gateway   # 改配置后单独重启
```