hailin
/
it0
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add comprehensive deployment guide 

Add deployment-guide.md covering build, deployment, and operations
for the entire IT0 platform including all microservices, web admin,
Flutter app, and voice service.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
hailin 2026-02-18 16:54:00 -08:00
parent e761b65b6e
commit 8116f17fd0
1 changed files with 625 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

625
docs/deployment-guide.md Normal file
View File

@ -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 <name> # 启动指定服务
./deploy.sh rebuild-svc <name> # 重建并重启指定服务
```
### 监控与日志
```bash
./deploy.sh status # 查看容器运行状态
./deploy.sh health # 健康检查所有服务
./deploy.sh logs # 查看所有日志
./deploy.sh logs <service> # 查看指定服务日志
```
### 基础设施
```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 <svc> <name> # 生成迁移
./deploy.sh migrate-revert <svc> # 回滚迁移
./deploy.sh schema-sync <svc> # 同步 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` — 验证所有服务健康