1.2 Docker Compose 部署

Docker Compose 一体部署把 MoAI 和全部依赖打包在一起，一条命令拉起整套服务，是最快的部署方式，适合自建服务器、内网环境和快速体验。

部署内容

服务	镜像	宿主机端口	用途
`moai`	`whuanle/moai:latest`	`8080`	MoAI 应用（前端 + 后端一体）
`postgres`	`pgvector/pgvector:pg16`	`5432`	PostgreSQL 数据库（带 pgvector 向量扩展）
`redis`	`redis:7-alpine`	`6379`	缓存与用户状态
`rabbitmq`	`rabbitmq:3-management-alpine`	`5672` / `15672`	消息队列（15672 为管理控制台）
`rustfs`	`rustfs/rustfs:latest`	`9000` / `9001`	S3 兼容对象存储（9000 为 S3 API，9001 为控制台）
`opensandbox-server`	`opensandbox/server:latest`	`18123`	沙箱生命周期服务

另有 rustfs-init 一次性容器负责建桶，不常驻。

图数据库（Memgraph / Neo4j）不内置。知识图谱为可选能力，需要时见文末「接入知识图谱」。

前置条件

Docker Engine ≥ 20.10、Docker Compose v2
放行端口：8080（MoAI）、9000/9001（RustFS）、18123（OpenSandbox）及各中间件端口
内存建议 ≥ 2 GB；沙箱运行时另需 Docker 可用磁盘空间

快速开始

在仓库根目录执行：

cp .env.example .env          # 按需修改账号/端口；MOAI_SERVER_URL 留空会自动探测
bash deploy/deploy-compose.sh

部署脚本会依次完成：

检查并载入 .env（不存在时自动从 .env.example 复制）；
按环境变量生成应用配置 configs/system.json（旧文件自动备份为 .bak）；
拉取全部依赖镜像，包括沙箱运行时镜像（opensandbox/code-interpreter、execd、egress）；
拉取 MoAI 镜像并启动全部服务（拉取失败时自动回退为本地源码构建）。

启动完成后访问 http://<服务器IP>:8080，种子账号 admin / abcd123456（root，登录后请立即改密）。

也可以本地构建镜像后部署：BUILD=1 bash deploy/deploy-compose.sh。

手动启动（不跑脚本）

bash deploy/deploy-compose.sh   # 至少执行一次以生成 configs/system.json
docker compose up -d

注意：直接 docker compose up -d 不会做 IP 自动探测。请在 .env 显式设置 MOAI_SERVER_URL 与 S3_ENDPOINT，否则对外地址会回退为 http://localhost:8080 / http://localhost:9000。

.env 配置要点

.env 是 Compose 部署的唯一配置来源，脚本据此生成 configs/system.json 挂载进容器，无需手写应用配置。完整变量表见配置。

最常需要改的几项：

变量	说明
`MOAI_SERVER_URL`	对外访问地址（含协议），如 `https://moai.example.com`。使用域名或 HTTPS 时必须显式填写，留空只会自动探测本机 IP
`S3_ENDPOINT`	对象存储对外地址。使用外部 OSS 时填写，留空用内置 RustFS 的 `http://<IP>:9000`
`POSTGRES_PASSWORD` / `RABBITMQ_PASSWORD` / `S3_ACCESS_KEY_SECRET`	生产环境务必改掉默认密码
`MOAI_AES_KEY`	AES 加密密钥，生产环境改为随机串

地址为什么重要

对象存储走浏览器预签名直传，S3_ENDPOINT 的地址必须同时被 MoAI 容器和用户浏览器访问到。所以：

默认自动探测出的 http://<本机IP>:9000 是可以正常工作的；
不要把它写成 http://rustfs:9000（浏览器解析不了容器服务名）或 127.0.0.1（浏览器指向用户自己）；
使用域名 + HTTPS 反向代理时，同时设置 MOAI_SERVER_URL=https://moai.example.com 和 S3_ENDPOINT=https://oss.example.com。

组件说明

PostgreSQL：必须用 pgvector 镜像

数据库镜像硬约束为 pgvector/pgvector:pg16（或任何自带 pgvector 的镜像），不能用官方 postgres 镜像。MoAI 启动时需要 vector 扩展建向量索引，裸 postgres 镜像没有该扩展，首次建库即失败。compose 已通过 init-pgvector.sql 在首次初始化时自动创建 vector 与 uuid-ossp 扩展，之后 MoAI 启动会自动建表，无需手工迁移。

RustFS：S3 兼容对象存储

S3 API 在 :9000，Web 控制台在 :9001（账号见 .env 的 S3_ACCESS_KEY_ID/S3_ACCESS_KEY_SECRET）；
rustfs-init 容器会在 RustFS 就绪后幂等创建桶（默认 moai）；
数据持久化在 rustfs_data 卷中；
换用外部 OSS（阿里云 OSS、AWS S3、COS 等）时：在 .env 设置 S3_ENDPOINT 与 S3_* 凭据，然后可以从 compose 中删除 rustfs 与 rustfs-init。

浏览器直传跨域（CORS）

前端直传对象存储时，若 MoAI 站点与对象存储地址不同源，浏览器会校验 CORS 响应头：

默认（推荐）：在 .env 设置 RUSTFS_CORS_ALLOWED_ORIGINS=https://moai.example.com（多个用逗号分隔）；
RustFS 前面有 Caddy/nginx 反代时：由反代统一加 CORS 头，同时把 RUSTFS_CORS_ALLOWED_ORIGINS 置空。

⚠️ CORS 头只能加一层。RustFS 自带与前置反代同时开启，会出现 Access-Control-Allow-Origin: *, * 导致浏览器报错。

OpenSandbox：沙箱服务

沙箱用于技能执行、代码解释器等场景，是独立容器而非打进 MoAI 镜像：沙箱服务需要访问宿主机 Docker（通过挂载 docker.sock 创建沙箱容器），独立部署可以避免 MoAI 容器持有 Docker 控制能力，缩小安全面。

镜像	说明
`opensandbox/server:latest`	生命周期服务，compose 中常驻运行
`opensandbox/code-interpreter:v1.1.0`	沙箱运行时，按需创建，部署时只预拉取
`opensandbox/execd:v1.1.0`、`opensandbox/egress:v1.1.7`	沙箱执行与网络组件，运行时由服务端拉取

受限网络可改用阿里云镜像：sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/server:release-1.1.0（.env 的 OPENSANDBOX_SERVER_IMAGE）。

默认 OPENSANDBOX_INSECURE_SERVER=YES 表示未启用沙箱服务鉴权，仅建议内网可信环境使用；生产环境建议在 deploy/opensandbox/sandbox.toml 中配置 server.api_key，并同步到应用配置的 OpenSandBox.ApiKey。

常用命令

docker compose ps                # 服务状态
docker compose logs -f moai      # 跟踪 MoAI 日志
docker compose down              # 停止（保留数据卷）
docker compose down -v           # 停止并删除数据卷（危险，清空全部数据）

升级与备份

# 升级 MoAI（依赖服务不动）
docker compose pull moai && docker compose up -d moai

# 备份 PostgreSQL
docker exec moai-postgres pg_dump -U postgres moai > moai-$(date +%F).sql

# 备份对象存储数据卷
docker run --rm -v moai_rustfs_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/rustfs-data.tgz /data

# 备份上传文件卷
docker run --rm -v moai_moai_files:/data -v "$PWD":/backup alpine \
  tar czf /backup/moai-files.tgz /data

数据卷名带 compose 项目名前缀（项目名为 moai），可用 docker volume ls 核对。

接入知识图谱（可选）

知识图谱模块依赖图数据库，默认不部署。需要时单独部署 Memgraph 并在 MoAI「系统设置 → 图数据库」中开启：

docker run -itd --name memgraph \
  -p 7687:7687 -p 17444:7444 \
  -v memgraph_data:/var/lib/memgraph \
  -e MEMGRAPH="--storage-snapshot-interval-sec=300 --storage-snapshot-on-exit=true" \
  memgraph/memgraph-mage

连接配置：

连接地址：bolt://<host>:7687（MoAI 容器访问宿主机用 bolt://host.docker.internal:7687）
用户名/密码：留空（Memgraph 社区版默认无鉴权）
方言：memgraph（接入外部 Neo4j 时选 neo4j）

社区版 Memgraph 默认纯内存存储，务必保留示例中的快照参数，否则容器重启会丢数据。

上一篇1.1 Docker 部署下一篇1.3 Kubernetes 部署