1.1 Docker 部署
Docker 单容器部署只运行 MoAI 一个容器，PostgreSQL、Redis、RabbitMQ、对象存储等依赖由外部环境提供，适合已有中间件资源的场景。如果希望开箱即用、连依赖一起部署，请直接看下一章 Docker Compose。
镜像说明
MoAI 采用前后端一体镜像：前端编译为静态资源放在后端 wwwroot，由 .NET 后端同源托管，不需要单独部署前端。
| 项 | 说明 |
|---|---|
| 镜像 | whuanle/moai:latest（Docker Hub） |
| 平台 | linux/amd64、linux/arm64 |
| 容器端口 | 8080 |
| 配置加载 | 环境变量 MAI_FILE，默认 /app/configs/system.json |
前置条件
- Docker Engine ≥ 20.10
- 已放行宿主机端口
8080 - 外部依赖已就绪：
| 依赖 | 要求 |
|---|---|
| PostgreSQL | 必须带 pgvector 扩展（如 pgvector/pgvector 镜像或自装扩展的实例），且已启用 vector、uuid-ossp 两个扩展 |
| Redis | 任意 5.x/6.x/7.x 实例 |
| RabbitMQ | 任意 3.x 实例 |
| 对象存储 | S3 兼容存储（MinIO、RustFS、阿里云 OSS、AWS S3 等） |
| OpenSandbox（可选） | 沙箱技能运行时，不配置时仅影响沙箱执行类功能 |
数据库扩展安装一次即可：
CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
MoAI 首次启动会自动创建全部数据表并写入种子数据，无需手工执行迁移脚本。
准备配置文件
复制模板并按外部服务修改连接信息：
mkdir -p configs
cp configs/system.example.json configs/system.json
需要修改的字段（完整字段说明见 配置）：
| 字段 | 说明 |
|---|---|
MoAI:Server / MoAI:WebUI | 浏览器访问 MoAI 的地址（含协议），如 https://moai.example.com |
MoAI:Database | PostgreSQL 连接串，Host 指向外部数据库 |
MoAI:Redis | 如 redis:6379 改为实际地址 |
MoAI:RabbitMQ | 如 amqp://user:pass@rabbitmq:5672 改为实际地址 |
MoAI:Storage | S3 兼容存储的 Endpoint、Bucket、AccessKey |
MoAI:AES | 加密密钥，生产环境务必改为随机串 |
如果外部依赖跑在同一台宿主机上，容器内访问宿主机服务用 host.docker.internal（Linux 需要给容器加 --add-host host.docker.internal:host-gateway，见下方启动命令）。
启动
docker run -d \
--name moai \
--restart unless-stopped \
-p 8080:8080 \
-e MAI_FILE=/app/configs/system.json \
-e TZ=Asia/Shanghai \
--add-host host.docker.internal:host-gateway \
-v "$(pwd)/configs/system.json:/app/configs/system.json:ro" \
-v moai_files:/app/files \
whuanle/moai:latest
挂载的配置文件必须真实存在。宿主机缺少
configs/system.json时，Docker 会在挂载点自动创建一个同名目录，容器启动即报错退出。补齐文件后docker rm -f moai重新启动即可。
请始终挂载完整配置文件启动。不要试图用 -e 环境变量零散注入配置：system.json 包含数据库、Redis、RabbitMQ、对象存储、加密密钥等几十项配置，环境变量只覆盖个别字段，其余仍是模板默认值，极易遗漏出错。
验证
# 服务信息接口应返回 JSON
curl -fsS http://localhost:8080/api/common/serverinfo
# 查看启动日志
docker logs -f moai
浏览器打开 http://localhost:8080，使用种子账号登录：
| 账号 | 密码 | 角色 |
|---|---|---|
admin | abcd123456 | root |
种子账号拥有最高权限，部署完成后请立即在「个人设置」中修改密码。
升级与回滚
# 升级到最新版
docker pull whuanle/moai:latest
docker rm -f moai
# 再执行一次上面的 docker run
# 回滚：改用固定版本 tag 启动，如 whuanle/moai:v1.0.0
建议生产环境使用固定版本 tag，方便回滚。
常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
启动报 system.json 是目录 | 宿主机配置文件不存在，Docker 把挂载点建成了目录 | 补齐文件后删除容器重启，确认挂载为「文件:文件」 |
| 启动报数据库连接失败 | Database 连接串错误或数据库不可达 | 核对 Host/Port/账号；容器内访问宿主机用 host.docker.internal |
启动报 vector 扩展相关错误 | 数据库没有 pgvector 扩展 | 换用带 pgvector 的实例或安装扩展后重启容器 |
| 上传文件 500 或 404 | Storage 未配置或端点不可达 | 核对 Storage 五项配置；预签名地址必须浏览器可达，见 配置 |
| 容器访问不到宿主机服务 | Linux 上 host.docker.internal 未映射 | 启动命令保留 --add-host host.docker.internal:host-gateway |
日志出现 Cannot load library libgssapi_krb5.so.2 | 运行时镜像缺 Kerberos 库的告警 | 不影响功能，可忽略 |