1.4 配置说明

MoAI 的应用配置集中在 system.json，Docker Compose 部署时则以 .env 为唯一配置来源、由部署脚本自动生成 system.json。本章说明两份文件的全部配置项，以及它们之间的关系。

配置加载机制

MoAI 通过环境变量 MAI_FILE 指定配置文件路径，容器内默认 /app/configs/system.json：

支持 .json、.yaml、.conf 三种格式；
文件不存在时回退到镜像内置模板，仅可用于本机冒烟，正式部署必须挂载完整配置；
Docker Compose 部署的配置链路：

.env（唯一配置来源）
  → deploy/deploy-compose.sh 生成 configs/system.json（旧文件备份为 .bak）
    → 挂载进容器 /app/configs/system.json
      → MAI_FILE 加载

也就是说：Compose 部署改 .env 后重跑部署脚本即可，不要手改生成的 system.json（会在下次生成时被覆盖）；单容器与 Kubernetes 部署则直接维护 system.json。

system.json

完整模板（仓库 configs/system.example.json，// 注释仅作说明）：

{
  "MoAI": {
    "Name": "MoAI",
    "Port": 8080,
    "Server": "http://192.168.1.10:8080",
    "WebUI": "http://192.168.1.10:8080",
    "AES": "please-change-this-aes-key",
    "Database": "Database=moai;Host=postgres;Password=moai123456;Port=5432;Username=postgres;Search Path=public",
    "Redis": "redis:6379",
    "RabbitMQ": "amqp://guest:guest@rabbitmq:5672",
    "OpenSandBox": {
      "Address": "http://opensandbox-server:8090",
      "ApiKey": "",
      "Image": "opensandbox/code-interpreter:v1.1.0",
      "TimeoutSeconds": 900,
      "RenewThresholdSeconds": 300
    },
    "Storage": {
      "Endpoint": "http://192.168.1.10:9000",
      "ForcePathStyle": true,
      "Bucket": "moai",
      "AccessKeyId": "moaiadmin",
      "AccessKeySecret": "moaiadmin123"
    },
    "MaxUploadFileSize": 104857600,
    "OTLP": {
      "Trace": "",
      "Metrics": "",
      "Protocol": 0
    }
  },
  "Serilog": { /* 日志配置，见文末 */ }
}

MoAI 节

字段	类型	说明
`Name`	string	应用名称，默认 `MoAI`
`Port`	int	容器内监听端口，默认 `8080`，保持默认即可（对外端口由 Docker 端口映射 / Ingress 决定）
`Server`	string	对外访问地址（含协议），前端用它拼接 `/static` 资源地址，必须与浏览器访问地址完全一致
`WebUI`	string	Web 端地址，通常与 `Server` 相同
`AES`	string	AES 加密密钥，用于加密存储中的敏感字段，生产环境务必改为随机串
`Database`	string	PostgreSQL 连接串，Npgsql 格式（见下）
`Redis`	string	Redis 地址，`host:port`
`RabbitMQ`	string	RabbitMQ 连接串，`amqp://用户:密码@host:port`
`OpenSandBox`	object	沙箱服务配置（见下）
`Storage`	object	S3 兼容对象存储配置（见下）
`MaxUploadFileSize`	int	上传文件大小上限，单位字节，默认 `104857600`（100 MB）
`OTLP`	object	OpenTelemetry 导出配置（见下）

Database 连接串

采用 Npgsql 标准格式，分号分隔：

Database=<库名>;Host=<地址>;Password=<密码>;Port=5432;Username=<用户>;Search Path=public

要求数据库实例已安装 pgvector 的 vector 扩展与 uuid-ossp 扩展；建表在首次启动自动完成，无需迁移脚本。

OpenSandBox（沙箱）

字段	说明
`Address`	沙箱生命周期服务地址，Compose 内为 `http://opensandbox-server:8090`；不使用沙箱可留空
`ApiKey`	沙箱服务鉴权 Key，与 `sandbox.toml` 的 `server.api_key` 保持一致；未启用鉴权时留空
`Image`	沙箱运行时镜像，默认 `opensandbox/code-interpreter:v1.1.0`
`TimeoutSeconds`	沙箱存活时间（秒），默认 900
`RenewThresholdSeconds`	剩余多少秒时自动续期，默认 300

Storage（对象存储）

字段	说明
`Endpoint`	S3 端点（含协议）。该地址会直接出现在预签名上传/下载 URL 中，必须同时被 MoAI 容器和用户浏览器可达
`ForcePathStyle`	是否路径风格访问。MinIO/RustFS 等自建存储用 `true`；阿里云 OSS 等 Virtual Hosted Style 存储用 `false`
`Bucket`	存储桶名，需预先创建（Compose 部署由 `rustfs-init` 自动建桶）
`AccessKeyId` / `AccessKeySecret`	访问凭据

地址填写三条纪律：

Compose 内置 RustFS 时填 http://<宿主机IP>:9000 这类浏览器可达地址；
不要填 http://rustfs:9000（容器服务名浏览器解析不了）或 127.0.0.1（指向浏览器本机）；
使用域名/HTTPS 时，Endpoint 与 Server 都要显式配置成最终对外域名。

OTLP（可观测性）

字段	说明
`Trace`	Trace 导出端点，如 `http://otel-collector:4317`；留空禁用
`Metrics`	Metrics 导出端点；留空禁用
`Protocol`	导出协议：`0` = gRPC，`1` = HTTP Protobuf

Serilog 节

标准 Serilog 配置，默认只输出控制台日志。MinimumLevel.Override 可按命名空间降噪（模板已预置了 EF Core、ASP.NET Core 等常见噪音源的 Warning 级别）。容器场景一般保持默认，日志收集交给容器运行时（docker logs / kubectl logs）。

.env（Docker Compose 专用）

.env 只在 Docker Compose 部署时使用，从仓库根目录的 .env.example 复制而来。部署脚本读取后生成 system.json 并控制各容器的端口与凭据。

MoAI 服务

变量	默认值	说明
`MOAI_IMAGE`	`whuanle/moai:latest`	应用镜像；本地源码构建时 compose 使用 build 结果
`MOAI_PORT`	`8080`	MoAI 映射到宿主机的端口
`TZ`	`Asia/Shanghai`	容器时区
`MOAI_SERVER_URL`	空	对外访问地址（含协议），写入生成的 `system.json` 的 `Server/WebUI`。留空自动探测本机 IP 生成 `http://<IP>:<MOAI_PORT>`；使用域名/HTTPS 必须显式填写
`MOAI_CONFIG_FILE`	`./configs/system.json`	生成的应用配置文件位置（挂载进容器）
`MOAI_AES_KEY`	`please-change-this-aes-key`	AES 加密密钥，生产必改

对象存储

变量	默认值	说明
`S3_ENDPOINT`	空	对象存储对外地址（含协议）。留空自动探测为 `http://<IP>:<RUSTFS_PORT>`；使用外部 OSS 时填写其端点
`S3_ACCESS_KEY_ID`	`moaiadmin`	AccessKey，同时作为 RustFS 控制台账号
`S3_ACCESS_KEY_SECRET`	`moaiadmin123`	AccessKey 密钥
`S3_BUCKET`	`moai`	桶名
`S3_REGION`	`us-east-1`	区域
`RUSTFS_IMAGE`	`rustfs/rustfs:latest`	RustFS 镜像
`RUSTFS_INIT_IMAGE`	`amazon/aws-cli:latest`	建桶用的初始化镜像
`RUSTFS_PORT` / `RUSTFS_CONSOLE_PORT`	`9000` / `9001`	S3 API / 控制台端口
`RUSTFS_CORS_ALLOWED_ORIGINS`	`*`	浏览器跨域直传允许的源，多个逗号分隔。生产建议填 MoAI 站点源；若前置反代已统一加 CORS 头则置空，两层同时开会报 `, ` 错误

数据库 / 缓存 / 消息队列

变量	默认值	说明
`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`	`postgres` / `moai123456` / `moai`	PostgreSQL 账号与库名，写入连接串；host 固定为 compose 服务名 `postgres`
`POSTGRES_PORT`	`5432`	宿主机映射端口
`REDIS_PORT`	`6379`	Redis 宿主机映射端口
`RABBITMQ_USER` / `RABBITMQ_PASSWORD`	`guest` / `guest`	RabbitMQ 账号
`RABBITMQ_PORT` / `RABBITMQ_MANAGEMENT_PORT`	`5672` / `15672`	AMQP / 管理控制台端口

沙箱

变量	默认值	说明
`OPENSANDBOX_SERVER_IMAGE`	`opensandbox/server:latest`	沙箱生命周期服务镜像（受限网络可换阿里云镜像）
`OPENSANDBOX_PORT`	`18123`	宿主机映射端口（容器内 8090）
`OPENSANDBOX_INSECURE_SERVER`	`YES`	`sandbox.toml` 未配置 `api_key` 时必须为 `YES`；生产建议配置鉴权后改回
`OPENSANDBOX_SANDBOX_IMAGE`	`opensandbox/code-interpreter:v1.1.0`	沙箱运行时镜像（仅预拉取）
`OPENSANDBOX_TIMEOUT_SECONDS`	`900`	沙箱存活时间（秒）
`OPENSANDBOX_RENEW_THRESHOLD_SECONDS`	`300`	续期阈值（秒）

可观测性

变量	默认值	说明
`OTLP_TRACE` / `OTLP_METRICS`	空	OpenTelemetry 导出端点，留空禁用
`OTLP_PROTOCOL`	`0`	`0` = gRPC，`1` = HTTP Protobuf

配置的维护原则：整套配置集中在一份文件里维护，不要用环境变量在容器启动时零散覆盖个别配置项——配置项之间有关联（对外地址、存储端点、跨域来源等），零散注入极易遗漏，出问题也难排查。

上一篇1.3 Kubernetes 部署下一篇2.1 生成数据分析报告