主机要求
一台装有 Docker Engine 与 2.24.4 或更新版本的 Compose 插件、Git 的 Linux 主机，并能访问你的模型密钥所属的服务商。不需要 GPU。整套服务运行三个容器：带 pgvector 的 Postgres、服务端与 worker，外加一个每次启动都会运行一次、用于修正上传卷属主的一次性容器。主机容量取决于并发用户数和文件处理量；此版本尚未公布经过测量的最低配置。首次启动
请在首次启动之前确定部署方式：演示数据在首次启动时写入，数据库密码在数据卷创建时设定。1
克隆仓库
2
编写 .env
.env
ENV 指定覆盖文件的名称，即 config.prod.yaml。任意一个受支持的模型密钥都可以，见配置。3
编写配置覆盖文件
按下一节的内容创建
config.prod.yaml。deploy.sh 只会接入一份已经以这个名字存在的覆盖文件，不会替你创建。如果反向代理运行在同一主机上，请在启动前在 compose.override.yaml 中把应用端口绑定到回环地址。4
启动
deploy.sh 会在 .env 缺少 PG_PASSWORD、PG_ENCRYPTION_KEY、CONFIG_ENCRYPTION_KEY、LOG_ENCRYPTION_KEY、JWT_KEY 时补上，拉取应用镜像（拉取不到时从本地检出构建），并启动 Postgres、服务端与 worker。把用户指向这台主机之前，继续完成下方验证。已运行过本地演示
保存真实记录时请建立一套全新部署。在演示仓库中打开PRODUCTION 只会阻止后续演示数据写入，不会删除已有的演示账号与读数。Postgres 密码在旧数据卷创建时已确定，更换加密密钥也会使已存内容无法读取；沿用旧卷不能得到干净的生产环境。
- 如果演示环境里有需要保留的内容，先在该环境运行
shell/backup.sh，并把备份以及与之匹配的.env和配置文件存到受保护的位置。这是一份安全副本，不是生产环境的初始数据库。 - 优先使用新的 Linux 主机或虚拟机。在那里克隆引擎，按首次启动从头完成
SEED_DEMO_DATA=false、生产覆盖文件、DATABASE_DECRYPTION_KEY和 HTTPS，最后再运行./deploy.sh。 - 必须复用同一台主机时，先在演示仓库运行
docker compose down；它会停止演示，但不会删除数据卷。然后把生产代码克隆到名称不同的目录，确保COMPOSE_PROJECT_NAME未设置或与演示不同，并在新目录按首次启动操作。Compose 按项目名给命名数据卷加前缀，因此新项目会得到空的 Postgres 和上传文件卷；旧演示环境仍单独保留。 - 完成部署验证后，注册新账号，只录入需要保存的真实记录。确认界面中没有演示账号或演示读数。演示备份单独保留；把它恢复到新环境会重新带入演示数据。
PRODUCTION 并不等于完成迁移。
生产模式
config.prod.yaml
PRODUCTION: true 后，只要还有预置登录码或任何 REPLACE_THIS_VALUE_IN_PRODUCTION 占位值，服务端就拒绝启动，也不会写入演示数据；报错会写明还剩哪些。EMAIL_PREDEFINE_CODES: {} 会移除两个演示账号，因为覆盖文件会替换整个值。
之后用户可以通过三种方式登录：在 Web 客户端用密码注册（POST /password/register）；配置邮件服务器后用邮箱验证码登录（EMAIL_FROM 以及 EMAIL_SMTP_HOST、EMAIL_SMTP_PORT、EMAIL_SMTP_USER、EMAIL_SMTP_PASS）；或使用在 config.devices.yaml 中配置的 Google、Apple 登录。
如果你自行管理数据库 schema，同时设置 BOOTSTRAP_SCHEMA: false。
密钥
./deploy.sh 首次运行时会把 PG_PASSWORD、PG_ENCRYPTION_KEY、CONFIG_ENCRYPTION_KEY、LOG_ENCRYPTION_KEY 与 JWT_KEY 写进 .env，每一项都用 openssl rand -hex 32 生成，且不会覆盖已经存在的值（.env 本身以 chmod 600 写入）。Compose 通过 env_file 把 .env 传给每个容器，因此 PG_PASSWORD 会同时到达 pg 服务（POSTGRES_PASSWORD）与应用本身，不需要在别处再写一遍。
DATABASE_DECRYPTION_KEY 是唯一一个 deploy.sh 不会自动生成的密钥：它以 REPLACE_THIS_VALUE_IN_PRODUCTION 占位值的形式存在于 config.devices.yaml 中，而 PRODUCTION: true 只要发现这个占位值还在，就会拒绝启动。请自己在 .env 中设置它，以覆盖配置文件里的值（环境变量的优先级高于任何配置来源）：
.env
openssl rand -hex 16 生成它：得到的 32 个 ASCII 字符会被直接用作 32 字节 AES 密钥，不会先按十六进制解码。
Postgres 只在创建空数据卷时应用 POSTGRES_PASSWORD。要把 PG_PASSWORD 换到已有的数据卷上，请先用 ALTER USER 修改密码，再同步更新 .env。
请把 .env 排除在版本控制之外，也不要在不同环境之间复用这些密钥：用一个密钥加密的数据，无法用另一个密钥读取。备份数据库和上传文件时，也要妥善保存 .env，以便恢复后读取加密记录。CONFIG_ENCRYPTION_KEY 加密的是你自己写进覆盖文件里、名称形如 _KEY、_PASSWORD 等的值（例如写进 config.prod.yaml 的某个设备 provider 凭据），对 .env 没有作用。
公网地址与 HTTPS
在服务端前面用反向代理终止 TLS，服务端监听端口 。以下示例在同一台主机上运行 Caddy。先把域名解析到该主机，并开放 80 和 443 端口供证书签发与 HTTPS 使用。在compose.override.yaml 中，把下方服务配置合并到「密钥」一节的覆盖文件：这样应用只接受来自宿主机的连接，并信任 Compose 网络预设网关上的代理。!override 不能省略；否则 Compose 会在新增回环绑定的同时保留原来的公网绑定，参见 Compose 合并规则。
compose.override.yaml
Caddyfile
health.example.com 换成你的域名。DNS 与端口就绪后，Caddy 会获取 HTTPS 证书，并转发原始 Host 与代理协议，详见 Caddy 的反向代理指南。如使用其他代理或网络布局，请将 FORWARDED_ALLOW_IPS 设为应用容器实际看到的代理地址。
config.prod.yaml
MCP_PUBLIC_URL 是这套部署的公网地址，服务端用它生成打印出来的链接与文件 URL。请用 HTTP_HEADERS 把 CORS 限制在你实际提供服务的源上。
不要把 Postgres 暴露到公网。compose.yaml 已经只在回环地址上发布它（），便于本机查看，这一项不需要改动。基础 Compose 文件把应用端口公开发布，因此请保留上面的回环地址覆盖配置。运行 docker compose config，确认最终的 mirobody.ports 只有回环绑定。
验证部署
在仓库目录检查容器状态和本机健康接口：mirobody 服务应显示为 healthy，响应中应有 version 和 agent 字段。然后打开公网 HTTPS 地址，用真实账号注册或登录，并确认个人 MCP URL 也以 https:// 开头。生产模式会拒绝预置的演示登录码；启动失败时，先查看 docker compose logs --tail 80 mirobody 和排错。
备份与升级
数据保存在 Postgres 数据卷中；当上传文件存放在本地磁盘而不是存储桶时，还保存在上传卷中。恢复演练与恢复操作见核验与恢复备份；引擎的备份与恢复参考详细解释各数据卷。 请按升级部署的顺序操作：备份数据与密钥、检查目标版本、切换代码、重启和验证。deploy.sh 运行 docker compose up -d --remove-orphans，会原地重建发生变化的服务；请为这次短暂重启安排维护时段。