# 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` — 验证所有服务健康