Cyrene/docs/deploy/os-environment-setup.md

启用昔涟完整 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

# 安装 WSL2（需管理员权限，可能需要重启）
wsl --install -d Ubuntu-22.04

如果 GitHub 无法访问，手动安装：

# 下载镜像
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 复制）：

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 组并设置密码。已存在则跳过。

cd backend/ai-core
go run ./cmd/main.go

启动日志中应显示：

主机操控管理器已就绪: 沙箱执行 + 文件隔离
完整OS环境管理器已就绪: backend=wsl
工具注册中心已就绪: ... os_exec, os_file, os_system ...

快速开始（Linux + Docker）

1. 拉取镜像

docker pull ubuntu:22.04

2. 配置 .env

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 测试：

# 通过 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 后端