diff --git a/docs/deployment-guide.md b/docs/deployment-guide.md new file mode 100644 index 0000000..f7a23ba --- /dev/null +++ b/docs/deployment-guide.md @@ -0,0 +1,625 @@ +# IT0 系统编译与部署指南 + +IT0 是一个 AI 驱动的服务器集群运维平台，采用 DDD + Clean Architecture + 微服务架构。本文档涵盖系统的编译、部署和运维全流程。 + +--- + +## 目录 + +- [架构概览](#架构概览) +- [前置依赖](#前置依赖) +- [项目结构](#项目结构) +- [安装依赖](#安装依赖) +- [本地开发](#本地开发) +- [编译构建](#编译构建) +- [Docker 部署](#docker-部署) +- [生产部署](#生产部署) +- [语音服务（GPU）](#语音服务gpu) +- [数据库迁移](#数据库迁移) +- [环境变量说明](#环境变量说明) +- [服务端口](#服务端口) +- [运维命令](#运维命令) +- [关键文件索引](#关键文件索引) +- [快速上手清单](#快速上手清单) + +--- + +## 架构概览 + +``` +客户端 (Web/App/语音) + │ + ▼ +Nginx (SSL/TLS 反向代理) + │ + ▼ +Kong API Gateway (:8000) + │ + ├── auth-service (:3001) JWT 认证与 RBAC + ├── agent-service (:3002) AI 代理编排（Claude CLI/API） + ├── ops-service (:3003) 运维任务管理 + ├── inventory-service (:3004) 服务器资产管理 + ├── monitor-service (:3005) 健康监控与告警 + ├── comm-service (:3006) 多渠道消息通知 + ├── audit-service (:3007) 审计日志 + └── voice-service (:3008) 语音交互（STT/TTS） + +基础设施: + PostgreSQL 16 ── 主数据库（Schema-per-Tenant 多租户隔离） + Redis 7 ── 事件总线（Redis Streams）+ 缓存 + 限流 +``` + +**技术栈：** + +| 组件 | 技术 | +|------|------| +| 后端微服务 | NestJS (TypeScript) | +| API 网关 | Kong 3.7 (DB-less 模式) | +| Web 管理端 | Next.js (React/TypeScript) | +| 移动端 | Flutter (Dart) | +| 语音引擎 | FastAPI + Pipecat + Whisper + Kokoro | +| 构建工具 | Turbo + pnpm Workspaces | +| 容器化 | Docker + Docker Compose | + +--- + +## 前置依赖 + +| 软件 | 版本要求 | 用途 | +|------|----------|------| +| Node.js | v18+ | 后端 NestJS 服务运行时 | +| pnpm | 最新稳定版 | 包管理器（Workspaces 支持） | +| Docker | 最新稳定版 | 容器化运行环境 | +| Docker Compose | v2.x+ | 服务编排 | +| Python | 3.11 | 语音服务 | +| Flutter | 最新稳定版 | 移动端 App 构建 | + +--- + +## 项目结构 + +``` +IT0/ +├── packages/ +│ ├── services/ # 微服务 +│ │ ├── auth-service/ # 认证服务 +│ │ ├── agent-service/ # AI 代理服务 +│ │ ├── ops-service/ # 运维服务 +│ │ ├── inventory-service/ # 资产服务 +│ │ ├── monitor-service/ # 监控服务 +│ │ ├── comm-service/ # 通信服务 +│ │ ├── audit-service/ # 审计服务 +│ │ └── voice-service/ # 语音服务 (Python) +│ ├── shared/ # 共享库 +│ │ ├── common/ # @it0/common 通用工具 +│ │ ├── database/ # @it0/database 数据层 +│ │ ├── events/ # @it0/events 事件总线 +│ │ ├── proto/ # @it0/proto gRPC 定义 +│ │ └── testing/ # @it0/testing 测试工具 +│ └── gateway/ # Kong API 网关配置 +├── it0-web-admin/ # Next.js Web 管理端 +├── it0_app/ # Flutter 移动端 +├── deploy/ +│ ├── docker/ # Docker 部署配置 +│ │ ├── docker-compose.yml # 主编排文件 +│ │ ├── docker-compose.voice.yml # GPU 语音覆盖 +│ │ ├── docker-compose.ssl.yml # SSL 代理覆盖 +│ │ ├── deploy.sh # 部署脚本 +│ │ ├── .env.example # 环境变量模板 +│ │ └── nginx/ # Nginx 配置 +│ └── k8s/ # Kubernetes 配置 +├── package.json # Monorepo 根配置 +├── turbo.json # Turbo 构建管道 +└── pnpm-lock.yaml # 依赖锁定文件 +``` + +--- + +## 安装依赖 + +```bash +# 在项目根目录执行，安装所有工作区依赖 +pnpm install +``` + +此命令会自动安装以下工作区的依赖： +- `packages/services/*` — 7 个 NestJS 微服务 +- `packages/shared/*` — 5 个共享库 +- `packages/gateway` — Kong API 网关 +- `it0-web-admin` — Next.js 前端 + +语音服务（Python）需单独安装： + +```bash +cd packages/services/voice-service +pip install -r requirements.txt +``` + +Flutter 移动端： + +```bash +cd it0_app +flutter pub get +``` + +--- + +## 本地开发 + +### 方式 A：Docker Compose（推荐） + +最简单的方式，一键启动所有服务和基础设施： + +```bash +cd deploy/docker + +# 1. 首次安装（自动生成 .env 及安全密钥） +./deploy.sh install + +# 2. 编辑 .env，填入必要配置 +vi .env +# 至少需要设置 ANTHROPIC_API_KEY + +# 3. 构建所有 Docker 镜像 +./deploy.sh build + +# 4. 启动所有服务 +./deploy.sh up + +# 5. 运行数据库迁移 +./deploy.sh migrate +``` + +启动完成后： +- Web 管理端：`http://localhost:3000` +- API 网关：`http://localhost:8000` + +### 方式 B：原生开发（热重载） + +适合需要频繁修改代码的开发场景： + +```bash +# 终端 1：启动基础设施（PostgreSQL + Redis） +cd deploy/docker +docker-compose up postgres redis -d + +# 终端 2：启动所有后端服务（Watch 模式，自动重载） +# 回到项目根目录 +pnpm dev + +# 终端 3：启动 Web 前端（可选，pnpm dev 已包含） +cd it0-web-admin +npm run dev +``` + +本地开发需要在根目录创建 `.env` 文件（参考 `.env.example`）： + +```env +DB_HOST=localhost +DB_PORT=5432 +DB_USERNAME=it0 +DB_PASSWORD=it0_dev +DB_DATABASE=it0 + +REDIS_URL=redis://localhost:6379 + +JWT_SECRET=your-jwt-secret-change-in-production +JWT_REFRESH_SECRET=your-refresh-secret-change-in-production + +AGENT_ENGINE_TYPE=claude_code_cli +ANTHROPIC_API_KEY=sk-ant-xxx +``` + +--- + +## 编译构建 + +### 后端服务（NestJS） + +```bash +# Turbo 并行构建所有服务（自动处理依赖关系） +pnpm build + +# 构建单个服务 +pnpm --filter @it0/auth-service build +pnpm --filter @it0/agent-service build +pnpm --filter @it0/ops-service build + +# 构建输出目录 +# packages/services/{service-name}/dist/ +``` + +每个 NestJS 服务使用 `nest build` 编译 TypeScript 到 JavaScript，输出到各自的 `dist/` 目录。 + +### Web 管理端（Next.js） + +```bash +cd it0-web-admin + +# 开发模式 +npm run dev + +# 生产构建 +npm run build +# 输出：.next/ 目录 + +# 启动生产服务 +npm run start # 默认端口 3000 +``` + +### Flutter 移动端 + +```bash +cd it0_app + +# 获取依赖 +flutter pub get + +# 代码生成（如有使用 build_runner） +flutter pub run build_runner build --delete-conflicting-outputs + +# 构建 Android APK +flutter build apk + +# 构建 iOS +flutter build ios +``` + +### 语音服务（Python） + +Python 服务无需编译，直接运行： + +```bash +cd packages/services/voice-service + +# 开发模式（自动重载） +uvicorn src.api.main:app --reload --port 3008 + +# 生产模式 +uvicorn src.api.main:app --host 0.0.0.0 --port 3008 --workers 4 +``` + +--- + +## Docker 部署 + +### Docker Compose 文件说明 + +| 文件 | 用途 | +|------|------| +| `docker-compose.yml` | 主编排文件，包含所有服务和基础设施 | +| `docker-compose.voice.yml` | GPU 覆盖层，为语音服务启用 NVIDIA GPU | +| `docker-compose.ssl.yml` | SSL 覆盖层，添加 Nginx 反向代理 + Certbot | + +### 构建镜像 + +```bash +cd deploy/docker + +# 并行构建所有镜像 +./deploy.sh build + +# 无缓存构建（完全重建） +./deploy.sh build-no-cache +``` + +### Docker 网络与卷 + +**网络：** +- `it0-network` — 所有服务共享的 bridge 网络 + +**数据卷：** + +| 卷名 | 用途 | +|------|------| +| `postgres_data` | PostgreSQL 数据持久化 | +| `certbot_webroot` | ACME 证书验证目录 | +| `certbot_certs` | SSL 证书存储 | +| `models` | 语音模型缓存（可选） | + +--- + +## 生产部署 + +### 完整流程 + +```bash +cd deploy/docker + +# 1. 首次安装（生成安全密钥和配置） +./deploy.sh install +# 自动生成： +# - JWT_SECRET（32 位随机字符） +# - JWT_REFRESH_SECRET（32 位随机字符） +# - VAULT_MASTER_KEY（64 位十六进制） +# - POSTGRES_PASSWORD（32 位随机字符） + +# 2. 编辑 .env 配置生产环境变量 +vi .env +# 必须手动设置： +# - ANTHROPIC_API_KEY +# - API_DOMAIN（如 it0api.szaiai.com） +# - WEB_DOMAIN（如 it0.szaiai.com） +# - CERT_EMAIL（如 admin@szaiai.com） + +# 3. 构建所有 Docker 镜像 +./deploy.sh build + +# 4. 获取 SSL 证书（Let's Encrypt） +./deploy.sh ssl-init + +# 5. 带 SSL 启动所有服务 +./deploy.sh ssl-up + +# 6. 运行数据库迁移 +./deploy.sh migrate + +# 7. 验证部署 +./deploy.sh health +``` + +### SSL/TLS 配置 + +Nginx 作为 SSL 反向代理，配置位于 `deploy/docker/nginx/`： + +| 文件 | 用途 | +|------|------| +| `nginx.conf` | 主配置（反向代理 + 限流 + 压缩） | +| `nginx-init.conf` | 初始配置（仅 HTTP，用于 ACME 验证） | +| `ssl-params.conf` | SSL 参数（Mozilla Intermediate 配置） | + +**SSL 特性：** +- TLS 1.2 + 1.3 支持 +- ECDHE 密钥交换 +- HSTS 预加载头 +- OCSP Stapling +- API 限流：30 请求/秒 +- Web 限流：50 请求/秒 +- Gzip 压缩 + +**生产域名映射：** +- `https://it0api.szaiai.com` → Kong Gateway (:8000) +- `https://it0.szaiai.com` → Web Admin (:3000) + +### 证书管理 + +```bash +# 获取证书（首次） +./deploy.sh ssl-init + +# 手动续期 +./deploy.sh ssl-renew + +# 查看证书状态 +./deploy.sh ssl-status +``` + +Certbot 容器会自动处理证书续期。 + +--- + +## 语音服务（GPU） + +语音服务使用以下模型： +- **STT（语音转文字）：** faster-whisper (large-v3) +- **TTS（文字转语音）：** Kokoro-82M +- **VAD（语音活动检测）：** Silero VAD +- **编排框架：** Pipecat + +### 启用 GPU 支持 + +```bash +# 使用 GPU 覆盖层启动 +./deploy.sh voice-up + +# 重建语音服务 +./deploy.sh voice-rebuild +``` + +GPU 模式通过 `docker-compose.voice.yml` 添加： +- NVIDIA GPU 设备访问 +- `DEVICE=cuda` 环境变量 +- 模型缓存卷挂载 + +### CPU 模式 + +默认使用 CPU 运行，在 `.env` 中设置： + +```env +VOICE_DEVICE=cpu +WHISPER_MODEL=large-v3 +KOKORO_MODEL=kokoro-82m +``` + +--- + +## 数据库迁移 + +IT0 使用 TypeORM 管理数据库迁移，采用 Schema-per-Tenant 多租户架构： + +```sql +-- 自动创建的 Schema +shared -- 跨租户共享数据 +tenant_default -- 默认租户 +tenant_{id} -- 各租户独立 Schema +``` + +### 迁移命令 + +```bash +# 运行所有服务的迁移 +./deploy.sh migrate + +# 生成新迁移 +./deploy.sh migrate-generate auth-service AddUserTable + +# 回滚上一次迁移 +./deploy.sh migrate-revert auth-service + +# 强制同步 Schema（仅开发环境） +./deploy.sh schema-sync auth-service +``` + +--- + +## 环境变量说明 + +### 必填变量 + +| 变量 | 说明 | 示例 | +|------|------|------| +| `POSTGRES_USER` | 数据库用户名 | `it0` | +| `POSTGRES_PASSWORD` | 数据库密码 | *自动生成* | +| `POSTGRES_DB` | 数据库名 | `it0` | +| `JWT_SECRET` | JWT 签名密钥 | *自动生成* | +| `JWT_REFRESH_SECRET` | Refresh Token 密钥 | *自动生成* | +| `VAULT_MASTER_KEY` | 凭证加密主密钥 | *自动生成* | +| `ANTHROPIC_API_KEY` | Claude AI API 密钥 | `sk-ant-xxx` | + +### 可选变量 + +| 变量 | 说明 | 默认值 | +|------|------|--------| +| `REDIS_PASSWORD` | Redis 密码 | 空（无认证） | +| `API_DOMAIN` | API 域名 | `it0api.szaiai.com` | +| `WEB_DOMAIN` | Web 域名 | `it0.szaiai.com` | +| `CERT_EMAIL` | Let's Encrypt 邮箱 | `admin@szaiai.com` | +| `TWILIO_ACCOUNT_SID` | Twilio 账号 SID | 空 | +| `TWILIO_AUTH_TOKEN` | Twilio 认证令牌 | 空 | +| `TWILIO_PHONE_NUMBER` | Twilio 电话号码 | 空 | +| `WHISPER_MODEL` | Whisper 模型版本 | `large-v3` | +| `KOKORO_MODEL` | Kokoro TTS 模型 | `kokoro-82m` | +| `VOICE_DEVICE` | 语音计算设备 | `cpu` | + +--- + +## 服务端口 + +### 内部端口（Docker 网络内） + +| 服务 | 端口 | 健康检查 | +|------|------|----------| +| Kong API Gateway | 8000 (代理) / 8001 (管理) | `GET /status` | +| Web Admin | 3000 | — | +| Auth Service | 3001 | `GET /api/health` | +| Agent Service | 3002 | `GET /api/health` | +| Ops Service | 3003 | `GET /api/health` | +| Inventory Service | 3004 | `GET /api/health` | +| Monitor Service | 3005 | `GET /api/health` | +| Comm Service | 3006 | `GET /api/health` | +| Audit Service | 3007 | `GET /api/health` | +| Voice Service | 3008 | `GET /health` | +| PostgreSQL | 5432 | — | +| Redis | 6379 | — | + +### Kong 网关路由 + +``` +/api/v1/auth → http://auth-service:3001 +/api/v1/agent → http://agent-service:3002 +/api/v1/ops → http://ops-service:3003 +/api/v1/inventory → http://inventory-service:3004 +/api/v1/monitor → http://monitor-service:3005 +/api/v1/comm → http://comm-service:3006 +/api/v1/audit → http://audit-service:3007 + +# WebSocket 路由 +/ws/agent → ws://agent-service:3002 +/ws/voice → ws://voice-service:3008 +``` + +--- + +## 运维命令 + +所有命令通过 `deploy/docker/deploy.sh` 执行： + +### 服务管理 + +```bash +./deploy.sh up # 启动所有服务 +./deploy.sh down # 停止所有服务 +./deploy.sh restart # 重启所有服务 +./deploy.sh start-svc # 启动指定服务 +./deploy.sh rebuild-svc # 重建并重启指定服务 +``` + +### 监控与日志 + +```bash +./deploy.sh status # 查看容器运行状态 +./deploy.sh health # 健康检查所有服务 +./deploy.sh logs # 查看所有日志 +./deploy.sh logs # 查看指定服务日志 +``` + +### 基础设施 + +```bash +./deploy.sh infra-up # 仅启动 PostgreSQL + Redis +./deploy.sh infra-reset # 重置基础设施（会删除数据！） +``` + +### SSL 证书 + +```bash +./deploy.sh ssl-init # 首次获取证书 +./deploy.sh ssl-up # 带 SSL 启动 +./deploy.sh ssl-renew # 手动续期证书 +./deploy.sh ssl-status # 查看证书状态 +``` + +### 数据库 + +```bash +./deploy.sh migrate # 运行迁移 +./deploy.sh migrate-generate # 生成迁移 +./deploy.sh migrate-revert # 回滚迁移 +./deploy.sh schema-sync # 同步 Schema（仅开发） +``` + +--- + +## 关键文件索引 + +| 路径 | 说明 | +|------|------| +| `package.json` | Monorepo 根配置（pnpm workspaces + Turbo 脚本） | +| `turbo.json` | Turbo 构建管道与缓存配置 | +| `deploy/docker/deploy.sh` | 生产部署脚本（核心） | +| `deploy/docker/docker-compose.yml` | 主 Docker Compose 编排文件 | +| `deploy/docker/docker-compose.voice.yml` | GPU 语音服务覆盖层 | +| `deploy/docker/docker-compose.ssl.yml` | SSL Nginx 代理覆盖层 | +| `deploy/docker/.env.example` | 环境变量模板 | +| `deploy/docker/nginx/nginx.conf` | Nginx SSL 反向代理配置 | +| `deploy/k8s/base/` | Kubernetes 部署配置 | +| `packages/gateway/config/kong.yml` | Kong 网关声明式配置 | +| `packages/gateway/Dockerfile` | Kong 网关 Dockerfile | +| `packages/services/voice-service/Dockerfile` | 语音服务 Dockerfile | + +--- + +## 快速上手清单 + +### 本地开发（Docker） + +- [ ] 安装 Docker、pnpm、Node.js v18+ +- [ ] `pnpm install` — 安装依赖 +- [ ] `cd deploy/docker && ./deploy.sh install` — 初始化配置 +- [ ] 编辑 `.env`，设置 `ANTHROPIC_API_KEY` +- [ ] `./deploy.sh build` — 构建镜像 +- [ ] `./deploy.sh up` — 启动服务 +- [ ] `./deploy.sh migrate` — 数据库迁移 +- [ ] 访问 `http://localhost:3000`（Web）和 `http://localhost:8000`（API） + +### 生产部署 + +- [ ] 准备服务器（Linux，已安装 Docker + Docker Compose） +- [ ] 克隆代码仓库 +- [ ] `cd deploy/docker && ./deploy.sh install` — 初始化配置 +- [ ] 编辑 `.env`，设置所有必要变量（API Key、域名、邮箱） +- [ ] `./deploy.sh build` — 构建镜像 +- [ ] `./deploy.sh ssl-init` — 获取 SSL 证书 +- [ ] `./deploy.sh ssl-up` — 带 SSL 启动 +- [ ] `./deploy.sh migrate` — 数据库迁移 +- [ ] `./deploy.sh health` — 验证所有服务健康