docs: Docker Compose 生产部署指南 + OS 环境配置文档
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,79 @@
|
||||
# Docker Compose 生产部署
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 1. 配置环境变量
|
||||
cp .docker.env.example .docker.env
|
||||
# 编辑 .docker.env，填入真实的 API Key 和密码
|
||||
|
||||
# 2. 配置 Caddyfile（有域名时）
|
||||
# 将 :80 替换为你的域名，并取消 HSTS 注释
|
||||
|
||||
# 3. 启动所有服务
|
||||
docker compose --env-file .docker.env up -d
|
||||
|
||||
# 4. 查看状态
|
||||
docker compose ps
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
## 服务清单
|
||||
|
||||
| 服务 | 端口 | 说明 |
|
||||
|------|------|------|
|
||||
| caddy | 80 / 443 | 反向代理，自动 HTTPS |
|
||||
| gateway | 8080 (内部) | API 网关 |
|
||||
| ai-core | 8081 (内部) | AI 核心 |
|
||||
| memory-service | 8091 (内部) | 记忆检索 |
|
||||
| voice-service | 8093 (内部) | 语音识别 |
|
||||
| iot-debug-service | 8083 (内部) | IoT 调试 |
|
||||
| postgres | 5432 (内部) | 数据库 (pgvector/pg16) |
|
||||
| redis | 6379 (内部) | 缓存 |
|
||||
| qdrant | 6333 (内部) | 向量数据库 |
|
||||
| minio | 9000 (内部) | 对象存储 |
|
||||
| searxng | 8080 (内部) | 搜索引擎 |
|
||||
|
||||
## 环境变量
|
||||
|
||||
所有变量在 `.docker.env` 中配置。必填项：
|
||||
|
||||
| 变量 | 说明 |
|
||||
|------|------|
|
||||
| `LLM_API_URL` | LLM API 地址 |
|
||||
| `LLM_API_KEY` | LLM API 密钥 |
|
||||
| `POSTGRES_PASSWORD` | 数据库密码 |
|
||||
| `JWT_SECRET` | JWT 签名密钥 |
|
||||
| `MINIO_SECRET_KEY` | MinIO 密钥 |
|
||||
|
||||
## 域名与 HTTPS
|
||||
|
||||
有域名时修改 [Caddyfile](../../Caddyfile)：
|
||||
|
||||
```caddy
|
||||
# 将 :80 改为你的域名
|
||||
your-domain.com {
|
||||
# 取消 HSTS 注释
|
||||
header {
|
||||
Strict-Transport-Security "max-age=31536000; includeSubDomains"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Caddy 会自动从 Let's Encrypt 申请证书，确保 `ACME_EMAIL` 已正确填写。
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
# 重新构建并启动单个服务
|
||||
docker compose up -d --build gateway
|
||||
|
||||
# 查看特定服务日志
|
||||
docker compose logs -f ai-core
|
||||
|
||||
# 停止所有服务
|
||||
docker compose down
|
||||
|
||||
# 停止并删除数据卷（危险）
|
||||
docker compose down -v
|
||||
```
|
||||
@@ -0,0 +1,116 @@
|
||||
# 启用昔涟完整 OS 环境
|
||||
|
||||
默认情况下，昔涟只能在受控沙箱中执行少量安全命令（`host_exec`）。启用完整 OS 环境后，她可以在 WSL/Docker 容器内自由编译代码、安装软件、运行复杂脚本等。
|
||||
|
||||
## 前置条件
|
||||
|
||||
| 宿主机 OS | 推荐后端 | 前置条件 |
|
||||
|-----------|---------|----------|
|
||||
| Windows 10/11 | WSL | WSL2 已安装 + Ubuntu 发行版 |
|
||||
| Linux | Docker | Docker 已安装并可用 |
|
||||
| macOS | Docker | Docker Desktop 已安装 |
|
||||
|
||||
## 快速开始（Windows + WSL）
|
||||
|
||||
### 1. 安装 WSL + Ubuntu
|
||||
|
||||
```powershell
|
||||
# 安装 WSL2（需管理员权限，可能需要重启）
|
||||
wsl --install -d Ubuntu-22.04
|
||||
```
|
||||
|
||||
如果 GitHub 无法访问，手动安装：
|
||||
```bash
|
||||
# 下载镜像
|
||||
curl -L -o ubuntu-wsl.tar.wsl "https://mirrors.tuna.tsinghua.edu.cn/ubuntu-releases/jammy/ubuntu-22.04.5-wsl-amd64.wsl"
|
||||
|
||||
# 导入
|
||||
wsl --import Ubuntu-22.04 C:\WSL\Ubuntu-22.04 ubuntu-wsl.tar.wsl
|
||||
```
|
||||
|
||||
### 2. 配置 .env
|
||||
|
||||
编辑 `backend/.env`（或从 `.env.example` 复制）：
|
||||
|
||||
```bash
|
||||
HOST_EXEC_BACKEND=wsl
|
||||
WSL_DISTRO=Ubuntu-22.04
|
||||
# WSL 内会自动创建此用户（首次调用时）
|
||||
WSL_USER=cyrene
|
||||
WSL_USER_PASSWORD=your-secure-password
|
||||
HOST_EXEC_MAX_TIMEOUT=300
|
||||
```
|
||||
|
||||
### 3. 重启 ai-core
|
||||
|
||||
首次启动时，WSL 后端会自动在发行版内创建 `WSL_USER` 用户（默认 `cyrene`），加入 sudo 组并设置密码。已存在则跳过。
|
||||
|
||||
```bash
|
||||
cd backend/ai-core
|
||||
go run ./cmd/main.go
|
||||
```
|
||||
|
||||
启动日志中应显示：
|
||||
```
|
||||
主机操控管理器已就绪: 沙箱执行 + 文件隔离
|
||||
完整OS环境管理器已就绪: backend=wsl
|
||||
工具注册中心已就绪: ... os_exec, os_file, os_system ...
|
||||
```
|
||||
|
||||
## 快速开始（Linux + Docker）
|
||||
|
||||
### 1. 拉取镜像
|
||||
|
||||
```bash
|
||||
docker pull ubuntu:22.04
|
||||
```
|
||||
|
||||
### 2. 配置 .env
|
||||
|
||||
```bash
|
||||
HOST_EXEC_BACKEND=docker
|
||||
SANDBOX_CONTAINER=cyrene-sandbox
|
||||
SANDBOX_IMAGE=ubuntu:22.04
|
||||
HOST_EXEC_MAX_TIMEOUT=300
|
||||
```
|
||||
|
||||
### 3. 重启 ai-core
|
||||
|
||||
启动日志中应显示：
|
||||
```
|
||||
完整OS环境管理器已就绪: backend=docker
|
||||
```
|
||||
|
||||
容器会在首次执行命令时自动创建。
|
||||
|
||||
## 验证
|
||||
|
||||
用 DevTools 或 API 测试：
|
||||
|
||||
```bash
|
||||
# 通过 API 发送消息，让昔涟使用 os_exec
|
||||
curl -X POST http://localhost:8080/api/v1/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"user_id": "admin",
|
||||
"session_id": "test",
|
||||
"message": "昔涟，帮我在 OS 环境里看一下系统版本"
|
||||
}'
|
||||
```
|
||||
|
||||
检查工具调用日志，应看到 `os_exec` 被调用（命令如 `uname -a`）。
|
||||
|
||||
## 故障排查
|
||||
|
||||
| 现象 | 原因 | 解决 |
|
||||
|------|------|------|
|
||||
| 启动日志显示 "完整OS环境管理器未配置" | `HOST_EXEC_BACKEND` 未设置或拼写错误 | 检查 .env，值必须是 `wsl` 或 `docker` |
|
||||
| WSL 执行超时 | WSL 发行版未运行 | `wsl -d Ubuntu-22.04 -- echo test` 测试 |
|
||||
| Docker 执行报错 "cannot create container" | 镜像不存在 | `docker pull ubuntu:22.04` |
|
||||
| `os_*` 工具不存在 | osManager 创建失败 | 检查启动日志的报错信息 |
|
||||
|
||||
## 安全说明
|
||||
|
||||
- `os_*` 工具在**隔离环境**（WSL2 虚拟机 / Docker 容器）中执行，不影响宿主机
|
||||
- 建议为 Docker 容器**限制资源**：`docker run --cpus=4 --memory=8g ...`
|
||||
- WSL2 的 `/mnt/c/` 可访问 Windows 文件，AI 可能会修改 C 盘文件。生产环境建议使用 Docker 后端
|
||||
Reference in New Issue
Block a user