docs: Docker Compose 生产部署指南 + OS 环境配置文档

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-30 08:49:07 +08:00
parent 617f44a2fb
commit 77d12aefa6
2 changed files with 195 additions and 0 deletions
@@ -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 后端