626 lines
16 KiB
Markdown
626 lines
16 KiB
Markdown
# 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` — 验证所有服务健康
|