EasyAI AI Gateway 部署

正式版本通过签名目录分发，可信公钥见公钥文件，updater 的固定镜像摘要见维护清单。不要使用验收分支的镜像或密钥替代正式发行资料。

本仓库只部署官方不可变镜像，不构建业务源码。API/Web 由 system-update/catalog.json 及不可变安装清单成组选择，默认稳定版。通用 updater 与 AIGC 平台共用实现、各实例独立运行。

安装

curl -fsS https://git.51easyai.com/wangbo/ai-gateway-deploy/raw/branch/main/system-update/trust-keys.json -o release-trust-keys.json
./install.sh --updater-image <官方完整digest引用> --trust-keys <可信公钥文件>
./manage.sh status

将维护清单中的 updater.image 与 updater.digest 用 @ 连接，即为安装参数要求的完整镜像引用。下载公钥后，将 --trust-keys 指向 ./release-trust-keys.json。当前公钥标识为 gateway-release-20261031；私钥不随部署包分发。

仅支持 Linux AMD64、Docker Compose v2。安装器不会覆盖已有 .env，也不删除数据库卷。首次安装完成后仍须按网关正式手册初始化管理员。updater 没有公网端口。

环境变量配置

首次安装使用 install.env.example，运行态字段说明见 .env.example。安装器会根据签名目录生成镜像引用、实例标识和随机密钥；首次安装前不要创建 .env。

cp install.env.example install.env
# 编辑 install.env，填写发行方给出的 updater digest 和可信公钥 JSON 路径。
set -a
. ./install.env
set +a
./install.sh --updater-image "$AI_GATEWAY_UPDATER_IMAGE" --trust-keys "$UPDATE_TRUST_KEYS_FILE"
./manage.sh status

install.env 需要手动导出，安装器不会自动加载它；修改该文件也不会改变已经安装的实例。它和生成的 .env 均已加入 Git 忽略。安装时核对正式维护清单的固定摘要，不要使用可变镜像标签。

配置	作用
AI_GATEWAY_UPDATER_IMAGE	必填，来自发行说明的 updater 完整 digest；示例命令将它传给安装器
UPDATE_TRUST_KEYS_FILE	必填，可信公钥 JSON 路径；示例命令将它传给安装器
AI_GATEWAY_API_PORT / AI_GATEWAY_WEB_PORT	宿主环回端口，默认 8088 / 5178；不会开放公网绑定
UPDATE_IMAGE_REGISTRY	默认官方仓库；镜像站仍须提供相同的已核验镜像
UPDATE_CATALOG_URL / UPDATE_MAINTENANCE_URL	留空使用官方目录；自定义来源必须是 HTTPS 且签名可信
UPDATE_SKIP_HOST_TIMER	默认 false，安装独立维护调度；临时测试才按需跳过

生成的 .env 包含数据库密码、JWT 密钥、Worker 密钥和更新器内部令牌，权限为 0600。备份时保护这些内容，不要提交到 Git 或粘贴到日志。已安装实例修改端口等运行配置后，通过 ./manage.sh up 应用；更新版本、通道和自动更新开关使用下面的管理入口。不要手工改写安装器生成的镜像摘要或 data/update-state 下的状态文件。

版本与更新管理

./manage.sh list
./manage.sh prefer stable
./manage.sh prefer latest
./manage.sh prefer version v0.6.3
./manage.sh check
./manage.sh update
./manage.sh auto on
./manage.sh auto off

开启自动更新后立即检查，之后每 600 秒读取正式目录；有符合已保存策略的新正式版本就自动检查并安装。指定版本达到后保持，普通更新不降级。单次 update <版本> 不改变策略。请求回复丢失时下次 update 先查询原任务，避免重复提交。

updater/run-maintenance.sh 与主 updater 一起交付，由安装器每十分钟调度。它使用固定的恢复执行镜像，主 updater 停止时仍可以维护。默认不需要 Watchtower。维护与产品更新共用部署锁；运行故障、未知迁移结果需要人工核对，不循环重装。

签名公钥、更新状态、数据库和媒体资料应备份；数据库备份与恢复资料不等于自动数据库回滚。不要删除 data/update-state 或原镜像来修复安装状态。

旧部署接入须先核对原 Compose project、数据卷、密钥和实际镜像；当前安装器不会自动覆盖旧目录。产品开发与本地验收进展见网关源码仓库的实施报告。