16 KiB

Raw Permalink Blame History

IT0 系统编译与部署指南

IT0 是一个 AI 驱动的服务器集群运维平台，采用 DDD + Clean Architecture + 微服务架构。本文档涵盖系统的编译、部署和运维全流程。

架构概览

客户端 (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                   # 依赖锁定文件

安装依赖

# 在项目根目录执行，安装所有工作区依赖
pnpm install

此命令会自动安装以下工作区的依赖：

packages/services/* — 7 个 NestJS 微服务
packages/shared/* — 5 个共享库
packages/gateway — Kong API 网关
it0-web-admin — Next.js 前端

语音服务（Python）需单独安装：

cd packages/services/voice-service
pip install -r requirements.txt

Flutter 移动端：

cd it0_app
flutter pub get

本地开发

方式 A：Docker Compose（推荐）

最简单的方式，一键启动所有服务和基础设施：

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：原生开发（热重载）

适合需要频繁修改代码的开发场景：

# 终端 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）：

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）

# 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）

cd it0-web-admin

# 开发模式
npm run dev

# 生产构建
npm run build
# 输出：.next/ 目录

# 启动生产服务
npm run start    # 默认端口 3000

Flutter 移动端

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 服务无需编译，直接运行：

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

构建镜像

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`	语音模型缓存（可选）

生产部署

完整流程

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)

证书管理

# 获取证书（首次）
./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 支持

# 使用 GPU 覆盖层启动
./deploy.sh voice-up

# 重建语音服务
./deploy.sh voice-rebuild

GPU 模式通过 docker-compose.voice.yml 添加：

NVIDIA GPU 设备访问
DEVICE=cuda 环境变量
模型缓存卷挂载

CPU 模式

默认使用 CPU 运行，在 .env 中设置：

VOICE_DEVICE=cpu
WHISPER_MODEL=large-v3
KOKORO_MODEL=kokoro-82m

数据库迁移

IT0 使用 TypeORM 管理数据库迁移，采用 Schema-per-Tenant 多租户架构：

-- 自动创建的 Schema
shared           -- 跨租户共享数据
tenant_default   -- 默认租户
tenant_{id}      -- 各租户独立 Schema

迁移命令

# 运行所有服务的迁移
./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 执行：

服务管理

./deploy.sh up                    # 启动所有服务
./deploy.sh down                  # 停止所有服务
./deploy.sh restart               # 重启所有服务
./deploy.sh start-svc <name>      # 启动指定服务
./deploy.sh rebuild-svc <name>    # 重建并重启指定服务

监控与日志

./deploy.sh status                # 查看容器运行状态
./deploy.sh health                # 健康检查所有服务
./deploy.sh logs                  # 查看所有日志
./deploy.sh logs <service>        # 查看指定服务日志

基础设施

./deploy.sh infra-up              # 仅启动 PostgreSQL + Redis
./deploy.sh infra-reset           # 重置基础设施（会删除数据！）

SSL 证书

./deploy.sh ssl-init              # 首次获取证书
./deploy.sh ssl-up                # 带 SSL 启动
./deploy.sh ssl-renew             # 手动续期证书
./deploy.sh ssl-status            # 查看证书状态

数据库

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

16 KiB Raw Permalink Blame History Unescape Escape

IT0 系统编译与部署指南

目录

架构概览

前置依赖

项目结构

安装依赖

本地开发

方式 A：Docker Compose（推荐）

方式 B：原生开发（热重载）

编译构建

后端服务（NestJS）

Web 管理端（Next.js）

Flutter 移动端

语音服务（Python）

Docker 部署

Docker Compose 文件说明

构建镜像

Docker 网络与卷

生产部署

完整流程

SSL/TLS 配置

证书管理

语音服务（GPU）

启用 GPU 支持

CPU 模式

数据库迁移

迁移命令

环境变量说明

必填变量

可选变量

服务端口

内部端口（Docker 网络内）

Kong 网关路由

运维命令

服务管理

监控与日志

基础设施

SSL 证书

数据库

关键文件索引

快速上手清单

本地开发（Docker）

生产部署

16 KiB

Raw Permalink Blame History