Docker 部署¶
Raven 的 Compose 部署将 WebUI 和 Python 环境构建到同一个镜像中。nginx 提供 WebUI， Raven 引擎负责 RPC、消息渠道、定时任务和其他网关服务。
启动容器¶
在仓库根目录运行：
cd docker
docker compose up
容器就绪后打开 http://127.0.0.1:18793。本地默认配置会自动完成登录。
镜像中运行的服务¶
此部署在一个容器中运行两个进程：
| 进程 | 职责 |
|---|---|
| nginx，端口 80 | 提供构建好的 WebUI，并将浏览器请求代理给引擎。 |
| Raven 引擎 | 在容器内的 127.0.0.1:18793 上运行 RPC 网关。 |
引擎只绑定容器内的回环地址，因此 nginx 与引擎运行在同一个容器中。WebUI 和 Python 环境 均从同一份源码构建。
登录¶
Compose 默认设置 RAVEN_AUTO_LOGIN=1，浏览器访问本地 WebUI 时会自动获得会话。
这一设置适用于仅允许本机访问的端口。
如果要远程暴露服务，请在 .env.local 中设置 RAVEN_AUTO_LOGIN=0。容器启动时会打印一次性
登录地址。会话 Cookie 有效期为 30 天，其凭据保存在持久化数据卷中，因此容器重启后仍然有效。
在运行中的容器内生成新的登录地址：
docker compose exec raven docker-entrypoint.sh signin
配置模型服务商¶
如果尚未预配置模型服务商，请在 设置 > 模型服务商（Settings > Model providers） 中添加。 配置会在下一轮生效，无需重启。
如果希望容器启动前就完成配置，请将以下内容写入 .env.local：
RAVEN_PROVIDER=anthropic
RAVEN_API_KEY=sk-ant-...
使用不需要 API 密钥的本地模型服务时，可以配置：
RAVEN_PROVIDER=ollama-chat
RAVEN_API_KEY=
RAVEN_API_BASE=http://host.docker.internal:11434
入口脚本会在每次启动时将这些服务商参数写入 Raven 配置，因此容器重启时以此处的值为准。
配置环境变量¶
docker/.env 保存已提交的默认值。可选文件 docker/.env.local 后加载，并覆盖默认配置。
凭据应写入 .env.local，该文件会被 Git 忽略。
持久化数据¶
Raven 将配置、工作区文件、会话、日志和记忆存储在 raven-data 卷的 /data 下。删除容器
不会删除该卷。下面的命令会同时删除卷及其中的全部数据：
docker compose down -v
运行 CLI 命令¶
除了 run 和 signin 之外的参数都会传给 Raven CLI：
docker compose exec raven docker-entrypoint.sh provider test anthropic
docker compose run --rm raven status
部署限制¶
- 默认 Compose 页面会向所有能访问发布端口的浏览器授予会话。请保持默认的
127.0.0.1绑定；如需远程暴露，请设置RAVEN_AUTO_LOGIN=0，并在服务前配置访问控制代理。 - 镜像不负责 TLS 终止。远程部署时，请在容器前配置 HTTPS 反向代理。
- 镜像不包含 TUI 构建产物。
raven tui需要ui-tui/中的构建包。 sandbox可选依赖默认关闭，命令在容器内执行。如需同时使用 Boxlite，可通过RAVEN_EXTRAS添加该依赖。- 镜像包含用于办公文件预览的 LibreOffice。如果不需要预览办公文件，可以用
RAVEN_OFFICE=0构建。