一键部署

公开版本以本仓库的版本目录和不可变清单为准。新老用户默认稳定版；最新版由管理员主动选择。原稳定版更新入口保持兼容，完整说明见 发布与选版更新。本功能的源码交付和测试验收不自动更新正式或客户环境。

客户环境必须先发布官方稳定镜像及 latest，再通过本仓库的标准更新入口拉取镜像。禁止在客户服务器通过业务源码、替换编译文件或客户专用派生镜像直接修复线上；部署方式例外仅限已确认的自有 *.51easyai.com 环境。详细要求见 客户稳定镜像发布与更新规范 和 协作规则。

Linux/Mac

git clone --depth 1 https://git.51easyai.com/wangbo/easyai.git && cd easyai && chmod +x start.sh && ./start.sh

也可以通过环境变量直接传入部署方式，脚本会跳过对应问答：

# IP 访问
DEPLOY_ACCESS=ip DEPLOY_IP=服务器IP ./start.sh

# 域名访问，不申请 HTTPS 证书
DEPLOY_ACCESS=domain DEPLOY_DOMAIN=demo.example.com DEPLOY_HTTPS=false ./start.sh

# 域名访问，并自动申请 HTTPS 证书
DEPLOY_ACCESS=domain DEPLOY_DOMAIN=demo.example.com DEPLOY_HTTPS=true CERTBOT_EMAIL=ops@example.com ./start.sh

Linux IP 模式会自动安装并配置 Nginx，浏览器统一访问 http://IP。公网只需放行 TCP 80；前端、API、WebSocket 和 ASG 分别通过 /、/api、/socket.io、/asg-api 反向代理，容器上游端口默认仅绑定 127.0.0.1。首次启动会初始化数据库和服务，核心容器默认有 180 秒启动宽限期，检查成功会立即通过；脚本等待所选服务恢复可用后，还会等待 Nginx 配置生效并核验入口，之后才报告完成。可通过 DEPLOY_HEALTH_TIMEOUT_SECONDS / UPDATE_HEALTH_TIMEOUT_SECONDS 调整等待时限（默认 600 秒）。

常用变量：

变量	说明
DEPLOY_ACCESS	ip 或 domain；未传时进入问答选择
DEPLOY_IP	IP 模式访问地址，如 10.0.0.8
DEPLOY_DOMAIN	域名模式访问地址，可带 http:// 或 https://，脚本会自动清理
DEPLOY_HTTPS	true/false，域名模式下是否申请 HTTPS 证书
DEPLOY_PUBLIC_API_BASE_URL	高级覆盖后端公开 API 地址，例如 https://api.example.com:8443/api
CERTBOT_EMAIL	申请 HTTPS 证书使用的邮箱，默认 wangbo@51easyai.com
DEPLOY_FORCE_RECONFIG	非空时即使已有 .env 也重新生成部署配置
DEPLOY_DRY_RUN	1 时只生成配置文件，不安装 Docker、不启动服务
DEPLOY_NON_INTERACTIVE	1 时缺少必要变量会直接报错，不再进入问答
DEPLOY_MAC_DOCKER_INSTALL	macOS 未安装 Docker 时使用，auto 自动安装或 manual 提示手动安装

安全密钥与 Canvas CLI 实时协作

start.sh / start.ps1 和 update.sh / update.ps1 会自动初始化并持久化鉴权安全密钥。首次安装或存量升级发现 WS_AUTH_WS_TICKET_SECRET 缺失、过短时，会生成新的高强度随机值，并确保 WS_AUTH_METHODS 包含 ws_ticket；Compose 会把同一密钥同时注入 easyai-server 与 ws-gateway。已有合格密钥会原样保留，重复启动或升级不会轮换，用户无需手动填写或复制密钥。

生成结果仅保存在本机 .env。除首次安装完成页会明确显示登录用的初始管理员密码外，脚本日志对其他安全密钥只显示变量名，不输出密钥内容。不要把 .env 提交到 Git；集群部署时，各 easyai-server / ws-gateway 实例必须使用同一份持久化配置。

API Key 加密与旧部署升级

新安装脚本自动生成独立凭据加密密钥；存量部署默认保留兼容模式，未升级脚本的用户只更新兼容镜像也可继续使用原 API Key 和平台凭据。首次接入使用 DEPLOY_ENABLE_CREDENTIAL_ENCRYPTION=true 执行新版更新脚本，完成历史迁移后关闭明文读取；已有密文时丢失密钥会拒绝启动。数据库归档与完整原 keyring、配置主密钥/JWT 分开备份；新版提供密钥导出/还原和覆盖前预检。操作步骤、Windows 入口、备份还原顺序和回滚条件见 API Key 加密部署与旧用户兼容。

初始管理员密码生命周期

首次安装时，部署脚本会生成 20 位随机密码，写入 .env 的 CONFIG_INITIAL_ADMIN_PASSWORD，并在部署完成页直接显示：

登录账号: admin
登录密码: <本次部署生成的随机密码>

后端只在数据库中不存在 admin 时读取该值并创建管理员。创建成功后，.env 中的值不再用于登录校验，修改该变量或执行升级都不会重置现有管理员密码。初始密码没有独立的自动过期时间，在管理员主动修改前持续有效，因此首次登录后应立即修改密码。

如果部署脚本检测到已有 .env，完成页不会把其中的值误报成当前密码：数据库已有 admin 时继续使用现有密码；数据库尚未创建 admin 时，可查看 .env -> CONFIG_INITIAL_ADMIN_PASSWORD。

容器网络连接

容器间统一通过 Docker 服务名解析，数据库使用 mongo、缓存使用 redis、后端使用 easyai-server、更新服务使用 watchtower，不再分配固定容器 IP。内部 TCP 监听使用仅属于业务网络的 easyai-server-internal 别名，保留沙箱网络隔离。启动和升级入口会迁移已知旧默认地址；存量部署需在维护窗口通过标准脚本更新全部受影响服务，详细步骤见 容器网络迁移说明。

后端公开 API 地址

后端返回文件、预签名上传和异步任务查询地址时，按以下优先级确定公开入口：

1. .env 中的 CONFIG_PUBLIC_API_BASE_URL。
2. 来自可信代理的当前请求地址（仅当请求来源命中 CONFIG_TRUSTED_PROXY 时读取转发 Header）。
3. 当前请求的直接 Host。

启动和升级脚本会在拉取镜像、重建服务之前校验并持久化 CONFIG_PUBLIC_API_BASE_URL：新 IP 部署使用 http://IP/api；域名部署中 DEPLOY_HTTPS=false 使用 http/ws，DEPLOY_HTTPS=true 使用 https/wss。IP 与域名模式的浏览器接口路径统一为 /api、/socket.io、/asg-api，只由 Nginx 监听地址和公开协议决定 origin。旧环境缺少该配置时，会依次从绝对 NUXT_PUBLIC_BASE_APIURL、WebSocket origin、首个 CONFIG_SECURITY_ORIGIN 推导。已有合法值保持不变，非法或无法推导时脚本会终止并提示修复。

CONFIG_SECURITY_ORIGIN 是可选的浏览器来源白名单：留空或不配置时后端默认允许所有来源，启动和升级脚本不会自动生成；显式配置一个或多个 http(s) Origin 时，脚本会校验格式并由后端按白名单限制访问。

已有外部 TLS、手工代理、自定义公开端口或特殊路径时，可在执行脚本前设置高级覆盖：

DEPLOY_PUBLIC_API_BASE_URL=https://api.example.com:8443/custom-api ./update.sh

也可以直接在 .env 中维护：

CONFIG_PUBLIC_API_BASE_URL=https://api.example.com:8443/api
CONFIG_TRUSTED_PROXY=127.0.0.1,10.0.0.0/8

新的 easyai-proxy.conf.sample 会为 /api/ 和 /mcp 转发保留客户端 authority 中的显式端口，并补齐 X-Forwarded-Host、X-Forwarded-Port；/api/ 继续发送 X-Original-Prefix: /api。脚本不会改写已经生成的本地 Nginx 配置，旧部署可先通过显式 CONFIG_PUBLIC_API_BASE_URL 生效，再按模板手工同步代理 Header。

模板同时为 JSON、CSS、application/javascript 和 Nuxt 常用的 text/javascript 开启 Gzip；text/event-stream 未加入压缩类型，SSE 和 WebSocket 保持流式传输。已经生成的域名配置不会随模板自动更新，旧部署需要手工把 text/javascript 加入现有 gzip_types，执行 nginx -t 成功后再无中断 reload。

前端静态资源默认使用 STATIC_ASSET_COMPRESSION=auto。浏览器支持 Brotli 时优先使用经过哈希和响应头验证的 CDN Brotli 资源；客户 CDN 尚未配置编码资源或验证失败时，自动切回 Nuxt 源站的 Brotli/Gzip，不会阻塞 Web 启动。旧部署更新 docker-compose.yml 后无需修改 .env 即可使用默认值。

私有化客户可继续只配置 NUXT_APP_CDN_URL。如果 CDN 已支持 canonical URL 的 Brotli，EasyAI 会自动识别；如果希望 EasyAI 代为发布三套资源，再填写 .env.sample 中的 STATIC_CDN_OSS_* 最小读写凭据。上传对象使用 __easyai_encoding/br 和 __easyai_encoding/gzip 固定前缀，并携带正确的 Content-Encoding。也可由客户自己的流水线按该目录协议上传，EasyAI只负责验证。紧急回退可设置 STATIC_ASSET_COMPRESSION=off。

CDN 验证结果保存在 ./data/cdn-init，并与当前前端构建标识绑定；升级后旧结果会被忽略。任何密钥都只应放在本机 .env 或安全配置中心，不要提交到仓库。

https.sh 单独执行时也可以跳过域名选择：

DEPLOY_DOMAIN=demo.example.com EASYAI_PROXY_CONF=demo.example.com.conf CERTBOT_EMAIL=ops@example.com ./https.sh

如需对已有 Nginx 配置追加或替换域名，可设置 EASYAI_PROXY_DOMAIN_ACTION=add|replace；未设置时默认追加。

Windows

在 PowerShell 中执行：

git clone --depth 1 "https://git.51easyai.com/wangbo/easyai.git" "easyai"; Set-Location "easyai"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1"

Windows 也支持变量方式跳过选择：

# 本机访问
$env:DEPLOY_ACCESS = "local"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1"

# 局域网访问
$env:DEPLOY_IP = "192.168.1.10"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1"

# 仅生成配置，不启动 Docker
$env:DEPLOY_IP = "127.0.0.1"
$env:DEPLOY_DRY_RUN = "1"
$env:DEPLOY_NO_WAIT = "1"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1"

Windows 脚本权限说明：PowerShell 默认禁止运行脚本，直接双击 start.ps1 会闪退。

• 推荐：使用 powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1" 执行，无需修改系统策略
• 或：以管理员身份打开 PowerShell，执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，之后可直接运行 .\start.ps1

---

🚀部署问题扫码咨询

旧宿主更新要求 Python 3.6+、PyYAML 与 UTF-8 语言环境；标准入口会先检查依赖。历史 8192MiB 无限额堆的明确预算迁移及失败恢复见旧宿主更新兼容与预检。

更新升级

客户更新默认顺序

未明确要求例外时，客户更新统一执行：核对原部署仓库是否最新 → 落后或缺少偏好能力时执行默认完整 ./update.sh → 在后台配置、保存并回读更新偏好 → 按偏好检查并更新 → 验证运行状态、业务及原数据。未配置偏好默认稳定版；没有明确要求时，不指定产品版本或组件版本，不用仅镜像更新或旧 Watchtower 入口替代完整流程。发现阻塞先列出问题及优化方案给用户审阅。详见 客户版本更新默认流程。

老用户原目录升级

升级保留原安装目录、.env、data/ 和 Docker 数据卷。**不要先执行 docker compose down、改名旧目录再重新安装，也不要删除数据卷。**脚本先核对现有容器的项目归属、数据库和上传目录的数据位置，再检查并拉取全部目标镜像，成功后才重建服务；失败会返回非零状态，不能把“收到更新请求”当作完成。

升级前先做可恢复的数据库备份，并确认上传文件、Redis 持久化数据及凭据加密密钥已保留。脚本自动把升级前 .env* 和 Compose 配置备份到权限受限的 data/deployment-backups/update-*；这份配置备份不包含数据库，也不能替代数据库备份。升级不重置管理员密码或轮换已有合格安全密钥。配置中已有的自定义 Compose 项目名会保留；如果现有容器属于另一个项目，或数据库将从旧绑定目录/数据卷切换到另一位置，脚本会在拉取、重建前停止，避免误建空库。

Git 安装的用户，在原目录执行：

cd ~/easyai
./update.sh

默认读取官方远程发布源中的正式稳定版。Linux 默认完整更新会自动接入 updater，不需要另跑迁移命令；明确的仅镜像或定向更新保留原方式与范围，Windows 原脚本兼容行为不变。

旧部署包没有 Git、或旧更新脚本无法自更新时，先把新版部署工具克隆到独立临时目录，再让工具在原安装目录迁移；不搬迁业务数据：

# Ubuntu/Debian：仅旧包配置迁移需要 PyYAML
sudo apt-get install -y python3-yaml
TOOL_DIR=$(mktemp -d /tmp/easyai-upgrade-tool.XXXXXX)
git clone --depth 1 https://git.51easyai.com/wangbo/easyai.git "$TOOL_DIR"
UPDATE_PROJECT_DIR="$HOME/easyai" UPDATE_MODE=full UPDATE_NON_INTERACTIVE=1 \
UPDATE_ADOPT_LEGACY_CONFIG=1 bash "$TOOL_DIR/update.sh"

请把示例中的原安装目录替换成实际路径。迁移先备份将被替换的配置与脚本，将旧 Compose 配置保存为私有覆盖文件，保留端口、数据卷和自定义配置；官方应用镜像改由发布记录选择。自定义镜像、额外覆盖链或无法安全识别的配置会阻止迁移，需要先核对差异。工具目录确认无用后可删除；不要删除原安装目录或备份。 已在 Compose 文件链中引用、且与官方 Git 历史完全一致的纯镜像覆盖文件，如与新版仓库文件重名，迁移会将原内容保存在私有配置目录并更新引用；非镜像配置或无法确认来源的文件仍会阻止迁移。

稳定版与指定版本

新安装、完整更新、仅镜像更新和页面更新默认共同读取官方远程 system-update/release-manifest.json，配套组件从匹配的产品记录及随部署工具提交的 system-update/deployment-components.json 独立基线解析。服务器部署及脚本、模板、配置更新必须先拉取本仓库已提交的部署版本，再执行仓库脚本，不能现场改配置构造部署结果。旧版“仅镜像更新”兼容入口继续读取远程清单；新选版的版本历史和偏好目标也只来自本仓库，不以服务器临时配置充当发布源。自定义 UPDATE_MANIFEST_URL 的发布源应同时提供 releases/<产品版本>.json；离线部署设置 UPDATE_MANIFEST_SOURCE=local，由运维同步维护完整记录。主服务、网页、网关、Worker、updater、治理和记忆服务独立发布，不能把同一个产品版本号拼到所有镜像后面。managed 模式业务组件和固定配套组件持久化各自的 tag@sha256。旧 Watchtower 模式的默认更新保留核心服务官方 latest 稳定别名，并在拉取前后核对清单摘要，后续仍能自动获取新版稳定镜像；显式固定版本仅用于受控测试或指定版本操作。updater 默认也保留官方稳定 latest，继续接受原有自维护更新。保留旧 VERSION=latest 部署的升级入口；不把日常候选版本自动当作稳定版。

仅在用户明确要求指定版本时，新安装可设置 DEPLOY_RELEASE_VERSION=完整版本号，升级可设置 UPDATE_RELEASE_VERSION=完整版本号；普通客户更新不传这些参数，按后台保存的偏好检查和安装。指定版本入口按产品记录选择组件，保留未变化的网关和 Worker 实际版本。明确授权单独测试或更新某个组件时才使用 UPDATE_SERVER_VERSION 等参数，并通过 UPDATE_SERVICES 明确范围。缺失记录、错误标签、匿名拉取失败或平台不符会在重建前终止。

Linux 定向更新后端时，可显式设置 UPDATE_LOCAL_AUTO_BACKUP_RETENTION_DAYS=3，把本地自动备份改为保留最近 3 天。脚本先备份配置，再保存 CONFIG_DB_MONGO_LOCAL_AUTO_BACKUP_RETENTION_DAYS；镜像必须声明支持该能力，否则在容器替换前停止。不传该选项保留既有策略。后端启动及成功完成自动备份后按天清理，保留期内的全部自动副本和手动备份保留；云端保留策略与备份记录不因本地到期而删除。本地副本与手动记录共享、文件最近被修改，或保留期内没有可用的本地自动备份时，先保留供核对。旧云端地址核验失败不阻止已配置的本地到期清理，云端保留清理仍等待原核验通过。

日常发布构建并推送完整版本标签；发布选定版本与客户安装选择分别授权，不能因此默认给客户指定版本。客户默认按上述完整流程更新；明确授权的指定版本或隔离测试才使用固定版本参数。脚本按正式产品记录持久化各组件引用到服务器 .env，组件标签与摘要用于安装一致性，不代表人工指定客户长期版本。配置只能由已提交的部署仓库与迁移脚本更新，不手工修改服务器 .env 或 Compose/覆盖文件。

选择官方网页镜像时，脚本同时补齐缺失的 UPDATE_WEB_VARIANT，让更新器在安装 tag@sha256 后仍能识别 SSR、no-SSR 或品牌类型；已有显式类型保持原值。Linux 完整更新会在替换业务服务之前和全部服务健康之后分别核验版本列表及网页类型，类型无法识别时不会报告更新成功。

latest / latest-no-ssr 仅作为已批准的稳定版指针。稳定提升可由用户明确指定完整版本，或由每日发布负责人按稳定版判定规则核对相对当前稳定版的全部变化、实际验收与风险后执行：纯 Bug 修复或局部增量/独立新功能，在既有核心链路回归与兼容通过、无重大架构风险时自动提升；独立新功能局部缺项不自动阻塞整包，用户明确验收确认作为有效证据。重构、核心流程大改或具体共享风险按证据决定。选定版本后运行 node scripts/promote-stable-release.mjs --version <版本> --confirm-version <同一版本>（先 --dry-run），按固定产物 digest 复制稳定别名、读回并生成稳定清单，再审查和提交；日常 deploy 不调用此入口，也不修改稳定清单。发布工具在修改稳定指针前会运行完整安装镜像预检；也可单独执行 bash scripts/check-deployment-release.sh --version <产品版本>。预检逐一验证默认安装所需镜像的匿名可访问性和 linux/amd64 平台，不拉取镜像层、不启动容器。该操作不重编业务镜像、不改业务环境版本。版本记录须包括独立 SSR/no-SSR 和实际使用的必要配套产物。

update.sh 脚本用于自动更新 EasyAI 应用，包含以下功能：

• 拉取整个仓库：执行 git pull 获取最新代码（docker-compose.yml、start.sh、.env.*.sample 等全部文件）
• 自动补齐缺失的环境配置文件（.env、.env.tools、.env.ASG、.env.AMS，从 .sample 生成且不覆盖已有文件）
• 每次默认执行 scripts/update-env.d/ 中的版本化环境配置迁移，只补缺失/空值和必要列表项，不覆盖已有非空配置
• 自动初始化 3D 模型转换内部令牌，拉取并启动独立 model-conversion-worker；通过数据库、队列连接和 Worker 健康检查后才显示更新成功。
• 仓库版本发生变化时自动切换到拉取后的新版更新脚本继续执行，确保本次新增的迁移立即生效
• 在重建服务前迁移并校验 CONFIG_PUBLIC_API_BASE_URL
• 兼容 docker compose 和 docker-compose 两种命令格式
• 按正式稳定记录或显式选择的产品版本拉取镜像，随后重建服务
• 等待主服务、Web 和 WebSocket 网关恢复可用后才报告成功；拉取失败、启动失败或恢复超时会明确报告失败

没有 updater 容器的旧用户仍保留 Watchtower 稳定版兼容入口。这不作为默认客户更新流程；应先核对部署仓库，在原目录执行默认完整 ./update.sh，由脚本自动补齐配置并创建 updater，无需另跑更新服务迁移命令。后台偏好不可用时先报告阻塞及方案，经用户明确要求才使用旧入口作为例外。

新安装默认启用可查询进度的在线更新模式。管理员在页面发起更新后，即使主服务重启导致原请求断开，页面也会根据任务编号继续查询最终结果。Linux 存量部署执行默认完整 ./update.sh 时，无论尚未配置更新模式，还是之前为 legacy_watchtower，都会自动接入 updater。脚本先备份原配置，保留已有密钥、数据挂载及网页类型，再补齐更新服务配置；Watchtower 改为仅维护 updater，业务服务由 updater 管理，避免两个执行器同时更新。拉取仓库后重新执行新版脚本时同样生效。明确选择“仅镜像更新”或使用 UPDATE_SERVICES 定向更新时仍保留原模式，避免扩大更新范围；Windows 现有脚本仍保留原有兼容行为。新模式只管理 easyai-server、easyai-web 和 ws-gateway，数据库、Redis、RabbitMQ 等基础服务仍按原部署流程维护。

更新执行器 easyai-updater 始终跟随官方 :latest，由 Watchtower 默认每 60 秒检查一次，同时由宿主机定时任务每六小时直接检查，提供两条独立维护路径。没有新镜像时不重建容器；业务更新持有部署锁时，本轮延后，下轮重试。发布后正常在下一次轮询发现，再经过镜像下载和启动检查，不能将 60 秒检查间隔表述为保证 60 秒内完成。任务状态保存在宿主机 data/update-state 中，自身更新或意外重启后继续恢复未完成任务。

完成新版标准接入后，宿主另每分钟读取正式仓库的部署维护数据，自动同步声明的部署提交、应用编号配置迁移并维护更新组件。后续前置条件迁移通过发布 system-update/maintenance.json 交付，无需每次让客户手工跑脚本；业务安装仍遵循原偏好和自动安装开关。发布方法、失败恢复及覆盖范围见数据驱动更新流程。

受控更新会直接读取官方远程目录/清单，但读取发布源不能证明客户部署仓库和配置已最新；人工或 Agent 执行客户更新时仍先完成仓库核对，必要时执行完整 update.sh，随后按保存的后台偏好检查。已接入的后台定时更新继续按其已保存偏好运行，不要求每次定时任务另行拉取宿主仓库。任务开始后保留已检查的清单和摘要，重启恢复使用同一目标。稳定清单表示经人类指定或每日稳定策略判定后实际提升的版本；只有正式提升入口更新 latest / latest-no-ssr，普通构建不写稳定别名，也不改变其他安装的偏好或自动安装开关。已订阅稳定且开启自动更新的实例仍按原计划消费稳定发布。

发布源不可用时会提示暂时无法检查更新，并保留当前服务；不会用历史清单宣称已是最新。UPDATE_MANIFEST_URL 可配置私有发布源，留空时使用官方部署仓库。离线部署可显式设置 UPDATE_MANIFEST_SOURCE=local，此时读取 Compose 只读挂载的本地清单；需要自行维护该清单。旧部署中的 UPDATE_MANIFEST_FILE 路径覆盖不再影响默认远程模式。

新安装、Linux 默认完整更新以及已有 updater 的部署无需手工编辑 .env。旧模式接入由 update.sh 自动完成，其余缺省值从 scripts/update-env.d/010-managed-system-update.env 应用以下缺省值：

SYSTEM_UPDATE_MODE=managed
COMPOSE_PROFILES=managed-update
WATCHTOWER_CORE_UPDATE_ENABLED=false
WATCHTOWER_UPDATE_TARGET=easyai-updater
SYSTEM_UPDATER_UPDATE_INTERVAL_SECONDS=60
UPDATE_HEALTH_TIMEOUT_MS=300000
DOCKER_CONFIG_FILE=
EASYAI_DEPLOYMENT_SCHEMA_VERSION=2

SYSTEM_UPDATE_INTERNAL_TOKEN 由 start.sh / update.sh 自动生成并持久化，不需要手工填写。UPDATE_HEALTH_TIMEOUT_MS 控制每个核心服务替换后的恢复等待时间，默认 300000 毫秒。脚本优先复用现有 Docker 登录配置；匿名安装没有认证文件时自动建立权限受限的空配置文件，避免挂载源被创建成目录。私有镜像仓库需要先执行 docker login；更新器与仅负责其自更新的 Watchtower 都会只读挂载 DOCKER_CONFIG_FILE 指向的 Docker 登录配置。默认完整 ./update.sh 会先拉取并启动 updater，确认更新偏好及版本列表接口可用后再替换业务服务；若配套更新器尚不支持选版或发布源不可用，恢复原配置并停止本次更新，业务服务尚未替换。确认全部服务恢复可用后才报告成功。更新服务就绪后，在支持新版版本管理的后台中刷新即可选择稳定版、最新版或指定版本；默认稳定版，原业务自动更新开关保持不变。选版界面由相应前端业务版本提供；仅发布 updater 不会更换业务镜像、增加旧页面没有的界面或自动安装最新版。

Watchtower 默认使用 latest。start.sh/update.sh 自动安装宿主机 cron，start.ps1/update.ps1 自动注册 Windows 计划任务；每六小时分别对 Watchtower 和已启用的 updater 执行 docker compose pull <服务>、docker compose up -d --no-deps <服务> 并确认健康状态。只在镜像或配置有变化时重建，拉取失败不会停止该服务的现有容器。一项维护失败仍继续处理另一项，日志保留各自结果并报告失败；因此 updater 的宿主机维护不依赖 Watchtower 可用。宿主机定时维护及仅镜像、定向更新会跳过尚未接入的 updater；Linux 默认完整 ./update.sh 自动完成接入。每分钟的 updater 检查由常驻 Watchtower 执行；宿主机六小时任务负责备用维护及 Watchtower 自身更新。Windows 任务使用当前登录用户，以便访问其 Docker Desktop；Docker 不可用时保留失败日志，下次计划重试。

受控部署的默认完整更新会把官方 docker-compose.updater-maintenance.yml 放在 Compose 合并顺序末尾，纠正历史覆盖中的 updater 固定标签或摘要，并将 Watchtower 的目标限定为 updater。历史覆盖文件和业务镜像保持原样。缺失间隔或旧默认值 86400 自动迁移为 60 秒，其他显式间隔保留。已接入的部署也会在转交业务更新前完成这项迁移。只维护更新组件、明确设置间隔时，可在同步正式部署仓库后执行 python3 scripts/bootstrap-managed-updater.py --maintenance-only --interval-seconds 60：备份配置，保留当前 updater 代码并解除固定引用，启动 Watchtower，由下一次真实轮询拉取官方新版，不发起业务版本更新。

内网启用更新、事件、历史、状态和健康接口，不映射主机端口。WATCHTOWER_API_KEY 与 WATCHTOWER_HTTP_API_EVENTS_TOKEN 是两个独立随机令牌，由 Bash 和 PowerShell 安全初始化流程补齐；浏览器只访问后端。新安装及默认整组升级使用独立 WATCHTOWER_SCOPE（easyai），防止启动时清理其他部署的 Watchtower；定向升级和自定义监控目标保留原 scope，避免未重建的容器标签与新范围不匹配。managed 模式只扫描 updater，legacy 模式仍只在明确提交业务更新时执行原更新链路。

定时任务按部署目录去重，重复运行部署脚本不会重复注册。最近一次结果写入 data/infrastructure-update/last-run.log。设置 INFRASTRUCTURE_AUTO_UPDATE_ENABLED=false 后再次执行部署脚本可移除本部署的宿主定时任务；不改变已运行 Watchtower 的计划。启用时，官方 Watchtower 的旧版本标签自动迁移到 latest，自定义 Watchtower 仓库或摘要保持原值；受控 updater 使用官方 latest。旧客户需先执行一次新版完整部署/更新脚本，之后官方 updater 新镜像由定时轮询获取；只发布仓库不能修改尚未同步的客户主机。发布到官方 Watchtower latest 的镜像应先通过部署及旧接口兼容验收。

两个页面入口共用计时和步骤窗口。updater 保存阶段完成时间到 data/update-state/jobs；无 updater 时后端保存任务和单任务锁到 MongoDB。刷新或重新登录后按站点与账号恢复任务查询。请求超时或服务断开不会自动创建另一项更新，旧接口无法读取的阶段会明确提示。后端重启时页面保留进度，提醒在 3–5 分钟后刷新检查版本；只有确认目标版本和服务恢复才显示完成。

正式版本检测以本仓库的发布目录和清单为准，openapi.51easyai.com 的运行版本不决定可安装版本。测试源仅用于独立测试实例，不改官方目录。日常镜像使用完整固定版本；单独的验收通过不等于稳定提升。按每日稳定策略或人类指定版本执行正式提升，并保留源码、镜像、风险判定、配置迁移、实际更新及恢复证据，禁止包含凭据。

以后新增必需环境变量时，在 scripts/update-env.d/ 增加新的编号 .env 文件即可，不需要继续把写入逻辑堆进 update.sh。迁移文件支持 KEY=value（仅在缺失或空值时写入）、KEY+=item（确保逗号列表包含该项），以及 @skip-if KEY=value（明确保留某种旧模式）；所有迁移每次都会执行并保持幂等。迁移失败会在拉取镜像前终止，避免使用半完成配置启动服务。

已经保存更新偏好或安装记录的 Linux 部署，默认完整 ./update.sh 也会先独立维护 updater：在共享更新锁内核对原任务、备份配置，拉取并核验部署仓库声明的官方稳定更新器，确认健康和偏好接口后，再按原偏好检查业务版本。更新器继续使用自己的稳定 latest 维护通道；业务版本、网页类型和自动更新开关不由这一步改写。仅镜像或定向更新保持原范围；已有丢失回执时先恢复原任务，不替换执行器或重复提交。

使用步骤

1. [首次执行，后续无需重复执行]添加执行权限，命令：

chmod +x update.sh

2. 执行更新（默认会 git pull 拉取整个仓库）

./update.sh

注意：update.sh 需要在 Git 克隆的目录下运行。若通过 zip 下载而非 git clone，请先使用 git clone 获取项目。

使用方式

• 执行 ./update.sh 后会命令行内选择更新方式：

  • [1] 更新并拉取仓库（git pull）+ 更新镜像并重启（默认，回车即选）
  • [2] 仅更新镜像并重启（跳过 git pull，适用于有本地修改不想被覆盖的场景）

• API Key 加密首次接入需要新版脚本及历史迁移，请按 加密升级说明 执行；只有尚未接入加密的旧部署可以继续仅更新兼容镜像。

• 如果本次不涉及配置文件更新（如 .env*、docker-compose.yml、easyai-proxy.conf* 无变更），可直接选择 [2]，仅更新后台服务镜像并重启即可。

• 自动化更新可通过变量跳过选择：

# 更新仓库 + 拉取镜像 + 重启（等同默认选 1）
UPDATE_MODE=full ./update.sh

# 仅拉取镜像 + 重启（等同选 2）
UPDATE_MODE=image ./update.sh

# 或使用布尔变量
UPDATE_SKIP_REPO_UPDATE=true ./update.sh

以下仅用于明确授权的 3D 转换服务首次上线或指定服务/版本更新，不是默认客户更新命令：

UPDATE_MODE=full UPDATE_NON_INTERACTIVE=1 \
UPDATE_SERVICES='easyai-server easyai-web model-conversion-worker' \
UPDATE_RELEASE_VERSION="<指定完整版本号>" ./update.sh

脚本拉取部署仓库后会切换到新版脚本，补齐缺失的转换配置；已有令牌、端口、数据卷和显式付费选择保持原值。指定 UPDATE_SERVICES 时只重建这些服务，不重建数据库等依赖；服务名称有误会在拉取镜像前终止。普通更新不指定该变量时保留原来的整组更新行为。转换容器只加入业务网络，不开放主机端口，不连接沙箱网络，不挂载 Docker socket，也不读取整个生产 .env。默认限额为 2 CPU、4 GiB、并发 1、单任务 300 秒、临时空间 2 GiB；原模型始终保留，轻量转换失败可使用原模型。

MODEL_CONVERSION_WORKER_VERSION 使用产品记录中的实际 Worker 版本及摘要，不继承产品 VERSION。单独指定组件时只接受固定版本；Worker 使用固定标签和已核验摘要，核心服务的旧 Watchtower 稳定别名按前文规则保留。混元付费通道默认关闭，自建转换失败不自动切换到付费服务。已有 updater 的页面更新仍按稳定清单管理三个核心服务；转换 Worker 的首次安装和配置升级使用上述 update 脚本完成。

测试候选版本时使用 UPDATE_RELEASE_VERSION=<已登记产品版本>，由更新脚本解析记录中的核心服务和转换 Worker 实际版本，无需手工改动远端 .env 或移动 latest 标签。版本号不合法时在修改配置前终止。

Linux 旧部署如果因本地 Compose 修改无法拉取仓库，可在检查差异后设置 UPDATE_ADOPT_LEGACY_CONFIG=1。脚本需要 Python 3 和 PyYAML；先校验合并配置，再将原始配置和冲突文件备份到 data/deployment-backups/，本地差异保存在 data/deployment-config/legacy-compose.json，仓库继续管理新增服务和配置。其他业务代码修改、未支持的文件冲突或无法表示的删除会阻止迁移，不启动容器。活动 Nginx 配置不会被改写。

旧目录如果曾手工复制过官方更新脚本、环境模板或 scripts/、system-update/ 中的文件，迁移会逐文件核对当前上游历史。只有内容与同一路径的官方历史版本完全一致时，才会先备份再交给 Git 更新；客户自行修改的脚本、无法确认来源的文件和符号链接仍会阻止迁移。

2025 年使用 comfy-server、comfyAI-web 和 comfyai 网络的 Git 安装，也使用上面的新版工具及原目录完整迁移入口。脚本先确认原目录、容器归属和官方镜像，备份原配置，再将旧的受跟踪 .env、代理配置分离为私有文件；保留原端口、网络和实际 Redis 数据卷，同时补齐新版只读后端需要的持久目录。已确认的旧模板固定地址及内部连接迁为容器名，保持新版动态地址规则，不将旧固定 IP 放回兼容覆盖。合并失败会恢复私有配置，下次同一完整入口继续原迁移。只有全部镜像、存储、资源和更新器能力通过检查后，才停止并重命名两个旧业务容器作为恢复副本，由标准 Compose 创建新服务；不删除数据卷。此兼容入口使用 Compose 的 !override 替换端口列表，实际 Compose 必须能通过配置校验，否则在原配置和容器变更前停止。自定义镜像、额外覆盖链、无法确认的网络或其他本地代码修改继续拒绝自动接管。

旧沙箱如果只是在原业务网络上增加了该网段内的固定 IP，迁移会采用新版独立沙箱网络并记录迁移字段，原文件保存在备份中；别名、额外网络等其他定制不会被静默删除，脚本会提示冲突字段并停止。

迁移默认保留本地固定镜像。如果已确认某个核心服务的旧 digest 应恢复为部署仓库的镜像定义，可显式指定该服务；只允许本次更新范围中的 easyai-server、easyai-web 或 ws-gateway，其他镜像和本地配置继续保留：

UPDATE_MODE=full UPDATE_NON_INTERACTIVE=1 \
UPDATE_SERVICES='easyai-server easyai-web' \
UPDATE_ADOPT_LEGACY_CONFIG=1 \
UPDATE_RESTORE_REPOSITORY_IMAGES='easyai-web' ./update.sh

该操作由脚本备份并迁移本地 Compose 差异，随后快进部署仓库；不需要直接编辑生产 Compose。脚本保留原有覆盖文件，并将仅含本次目标服务镜像定义的 data/deployment-config/repository-images.json 放在有效配置链末尾，避免历史覆盖再次固定旧镜像；其他服务及自定义参数保持。执行前仍须检查所有有效 Compose 文件。更新后须检查有效配置中的镜像及容器实际 digest。

没有自更新能力的历史脚本可先通过 Git 获取新版 update.sh 和 scripts/ 到临时目录，再以 UPDATE_PROJECT_DIR=/实际/easyai/目录 执行新版脚本；配置迁移、仓库更新和容器操作仍由 update.sh 完成。已有 managed updater 同样使用动态地址，主服务通过 easyai-updater 解析连接，不再保留固定容器地址。

• 查看帮助：./update.sh -h 或 ./update.sh --help

更新说明

• 脚本会执行 git pull 拉取整个仓库最新代码
• 拉取后会检查并补齐缺失的 .env、.env.tools、.env.ASG、.env.AMS（不会覆盖已有文件）
• 最后执行 docker compose pull 和 docker compose up -d 拉取镜像并重启服务
• 默认最多等待 300 秒确认核心服务恢复可用；可通过 UPDATE_HEALTH_TIMEOUT_SECONDS 调整

Windows 用户（update.ps1）

Windows 下使用 update.ps1，功能与 Linux 版一致：

.\update.ps1

• 执行后会命令行内选择：[1] 更新并拉取仓库 + 更新镜像（默认）；[2] 仅更新镜像
• 需在 Git 克隆的 easyai 目录下运行
• 也可通过变量跳过选择：

$env:UPDATE_MODE = "image"
$env:UPDATE_NO_WAIT = "1"
.\update.ps1

---

重要更新记录：

2026.07.16

1. 公开 URL 稳定化：新增 CONFIG_PUBLIC_API_BASE_URL，后端文件、预签名和任务查询地址不再依赖 Redis 中缓存的首次请求 Host。
2. 新装与升级迁移：Linux/macOS 和 Windows 启动、升级脚本会在重建服务前初始化并校验公开 API 地址，支持 IP 自定义 SERVER_HTTP_PORT、HTTP/HTTPS 域名和 DEPLOY_PUBLIC_API_BASE_URL 高级覆盖。
3. 代理端口透传：新 Nginx 模板为 /api/、/mcp 补齐公开 Host/Port Header；已有生成配置不会自动改写。

2026.07.15

1. 主服务 Node.js 堆内存上限：easyai-server 默认通过 NODE_OPTIONS 将 V8 old-space 堆上限设置为 8192 MiB，可在 .env 中使用 NODE_MAX_OLD_SPACE_SIZE 覆盖。该值只限制 V8 堆，不包含 Buffer、sharp/libvips 等 native 内存。
2. 生效要求：该参数仅在创建 Node.js 进程时读取，更新部署文件后需要在合适的维护窗口重建 easyai-server 容器。

2026.06.24

1. 主服务 sharp/native 内存护栏：easyai-server 默认关闭 sharp/libvips cache，并将 sharp 并发限制为 1；同时设置 MALLOC_ARENA_MAX=2、MALLOC_TRIM_THRESHOLD_=131072、MALLOC_MMAP_THRESHOLD_=131072、MALLOC_TOP_PAD_=131072，降低图片处理和大 Buffer 场景下 native RSS 持续膨胀风险。
2. 重 native 操作隔离：遮罩合并、alpha 反转等 sharp/raw 操作改为一次性子进程执行，处理完成后由 OS 回收子进程 native heap，避免主服务 [heap] 被撑大。
3. 生图 base64 输出收敛：模型返回的 base64 图片会先上传到 OSS，返回对象和 raw/debug 响应中不再长期保留大 base64 字符串。
4. 重启要求：该内存护栏必须在新进程启动时生效，更新后需执行 docker compose up -d easyai-server 或重建并重启主服务容器。

MongoDB 空闲内存滞留的显式处理入口见 MongoDB 空闲内存归还。

2026.06.22

1. Redis 资源护栏：Redis 增加 ./data/redis:/data 持久化挂载、maxmemory 2gb、appendfsync everysec，并禁用 RDB 快照，避免队列历史膨胀后占满内存和容器写层。
2. Mongo/主服务内存限制：Mongo 增加 --wiredTigerCacheSizeGB 1.5 和容器内存限制，easyai-server 增加内存限制，避免 8G 机器上 Redis/Mongo/Node 相互挤压触发 OOM。
3. 升级前置要求：如果线上 Redis 之前没有 /data 持久化挂载，必须先迁移数据，再重建容器。Linux 和 Windows 的启动、升级脚本都会在拉取镜像前检查现有 Redis 的挂载位置，不一致时停止部署。

Redis 数据迁移与重启步骤

执行前先做云盘快照或外部备份，并确认可用磁盘空间。不要删除或重建旧 Redis 容器，直到数据已经迁出并校验。

cd ~/easyai

# 1. 确认旧容器的 /data 未挂载到当前项目的 data/redis，并备份现有配置。
docker inspect --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Source}}{{end}}{{end}}' redis

# 2. 停止 Redis 后复制一致的数据目录；保留旧容器，直到新容器验收完成。
docker stop --timeout 60 redis
mkdir -p ./data/redis
docker cp redis:/data/. ./data/redis/

# 3. 将 ./data/redis 再备份到其他磁盘或安全位置，并校验 AOF 文件与 manifest。
#    若目标目录原本非空，先核对来源，不要覆盖。

# 4. 确认 docker-compose.yml 已包含 ./data/redis:/data，检查配置并只重建 Redis。
docker compose config --quiet
docker compose up -d --no-deps redis
docker exec redis redis-cli ping
docker inspect --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Source}}{{end}}{{end}}' redis

迁移后核对 Redis 数据库键数、aof_last_write_status:ok、后端 /content 和网站首页；后端若未自动恢复，再单独重启后端容器。队列历史清理应单独评估，不作为迁移的默认步骤。

2026.3.20

1. 新增 Agent 记忆服务（AMS）模块：新增 agent-memory（Agent 长期记忆）容器，复用 easyai-pgvector 数据库（需 pgvector 扩展），用于支持 Agent 对话记忆、向量召回与反馈能力。
2. 新增环境变量文件：新增 .env.AMS.sample 文件，包含记忆服务所需的全部环境变量。
3. 主服务 easyai-server 新增 MEMORY_TCP_HOST 和 MEMORY_TCP_PORT 环境变量，用于内部 TCP 微服务通信。
4. Nginx 代理：easyai-proxy.conf.sample 中新增 /ams-api/ 路径代理（可选）。

升级步骤

步骤一：更新文件

将以下文件更新到最新版本：

• docker-compose.yml
• easyai-proxy.conf.sample
• docker/postgres/init-pgvector.sql（PostgreSQL 首次启动时创建 vector 扩展）

新增文件复制到部署目录：

• .env.AMS.sample → 复制为 .env.AMS 并根据实际环境修改

步骤二：配置 .env.AMS

cp .env.AMS.sample .env.AMS

根据实际环境修改 .env.AMS 中的关键配置：

# PostgreSQL 连接（独立库 easyai_memory，与 .env.ASG 中账号密码一致）
MEMORY_DATABASE_URL=postgresql://easyai:easyai2025@easyai-pgvector:5432/easyai_memory?schema=public

# 主服务 API 地址（用于 Embedding 与对话压缩）
MEMORY_AI_BASE_URL=http://easyai-server:3001

# Embedding 模型与维度（需与主服务一致）
MEMORY_EMBEDDING_DIMENSION=1024
MEMORY_EMBEDDING_MODEL=text-embedding-v4

# 每日记忆整理（默认每天凌晨 2 点执行）
MEMORY_MAINTENANCE_ENABLED=true
# 升级首日建议 true，确认无误后再改为 false
MEMORY_MAINTENANCE_DRY_RUN=false
# 单轮每租户处理上限
MEMORY_MAINTENANCE_BATCH_SIZE=200
# 启用语义冲突裁决（复用会话总结模型，无需单独配置模型）
MEMORY_MAINTENANCE_LLM_ENABLED=true
MEMORY_MAINTENANCE_LLM_MAX_PAIRS=20

说明：

• MEMORY_MAINTENANCE_ENABLED：总开关，false 时不执行每日整理。
• MEMORY_MAINTENANCE_DRY_RUN：true 仅记录分析和审计，不执行软删除。
• MEMORY_MAINTENANCE_LLM_ENABLED：开启后冲突处理优先使用会话总结模型做语义裁决，失败会回退规则处理。
• MEMORY_MAINTENANCE_LLM_MAX_PAIRS：单轮最多调用模型裁决的冲突对数，用于控制成本。

步骤三：启动服务

记忆服务使用 Docker Compose Profile，需显式启用：

cd ~/easyai
# 启动全部服务（含记忆服务）
docker compose --profile memory up -d

# 或仅启动基础服务（不含记忆）
docker compose up -d

新增容器：agent-memory（Agent 记忆服务），复用 easyai-pgvector，使用独立库 easyai_memory。初始化流程与 ASG 一致：

• PostgreSQL 首次启动：docker/postgres/init-pgvector.sql 创建 vector、pgcrypto 扩展
• easyai-asg 启动：entrypoint 执行 prisma migrate deploy，创建治理相关表
• agent-memory 启动：entrypoint 执行 prisma migrate deploy，创建 memory_records 等表

注意：easyai-pgvector 使用 registry.cn-shanghai.aliyuncs.com/easyaigc/pgvector:0.8.2-pg18-trixie（含 pgvector 扩展）。若此前使用其他镜像且已有数据，升级前请备份 asg_postgres_data 卷。

步骤四：验证

# 检查容器状态
docker compose ps agent-memory

# 检查记忆服务健康状态
curl http://127.0.0.1:3004/health

# 通过 Nginx 代理访问（配置 Nginx 后）
curl https://<你的域名>/ams-api/health

注意：记忆服务默认不启动，使用 docker compose --profile memory up -d 显式启用。若不需要 Agent 记忆功能，保持 docker compose up -d 即可，主服务会正常运行（记忆相关能力不可用）。

---

2026.3.2

1. 新增 Agent 服务治理（ASG）模块：新增 easyai-asg（Agent 服务治理）容器和独立的 easyai-pgvector（PostgreSQL 18）数据库容器，用于支持 Agent 自动化治理能力。
2. 新增 Nginx 反向代理：在 easyai-proxy.conf.sample 中新增 /asg-api/ 路径代理，用于暴露 ASG 服务的 REST API。
3. 新增环境变量文件：新增 .env.ASG.sample 文件，包含 ASG 服务所需的全部环境变量。
4. 主服务 easyai-server 新增 ASG_TCP_HOST 和 ASG_TCP_PORT 环境变量，用于内部 TCP 微服务通信。
5. 前端新增环境变量：.env 中新增 NUXT_PUBLIC_SG_APIURL，用于前端治理管理页面调用 ASG API。

升级步骤

步骤一：更新文件

将以下文件更新到最新版本：

• docker-compose.yml
• easyai-proxy.conf.sample
• .env.sample（新增 NUXT_PUBLIC_SG_APIURL）

新增文件复制到部署目录：

• .env.ASG.sample → 复制为 .env.ASG 并根据实际环境修改

步骤 1.5：配置 .env 新增变量

在 .env 文件中添加 ASG 前端 API 地址：

# IP 直接访问方式
NUXT_PUBLIC_SG_APIURL=http://<你的服务器IP>:3003
# 域名 + Nginx 代理方式（需要配置步骤三的 Nginx 代理）
#NUXT_PUBLIC_SG_APIURL=/asg-api

步骤二：配置 .env.ASG

cp .env.ASG.sample .env.ASG

根据实际环境修改 .env.ASG 中的关键配置：

# PostgreSQL 连接（默认使用容器内网地址，一般无需修改）
ASG_DATABASE_URL=postgresql://easyai:easyai2025@easyai-pgvector:5432/agent_governance?schema=public
ASG_POSTGRES_USER=easyai
ASG_POSTGRES_PASSWORD=easyai2025

# Redis（复用主服务 Redis，使用独立 DB 隔离）
ASG_REDIS_HOST=redis
ASG_REDIS_PASSWORD=        # 与主服务 Redis 密码保持一致

# 主服务连接地址（容器内网地址）
ASG_MAIN_BACKEND_URL=http://easyai-server:3001
# 管理员账号（用于 Agent 调用时登录获取 token）
ASG_ADMIN_USERNAME=admin
ASG_ADMIN_PASSWORD=123456

步骤三：更新 Nginx 配置，暴露创建任务治理相关接口

在 nginx 配置文件（/etc/nginx/conf.d/easyai-proxy.conf）中添加 ASG API 代理，具体位置参考 easyai-proxy.conf.sample：

    location /asg-api/ {
        proxy_pass http://127.0.0.1:3003/;
        proxy_read_timeout 300s;
        client_max_body_size 20M;
        proxy_redirect off;
        proxy_set_header X-Original-Prefix '/asg-api';
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;
    }

添加后重载 Nginx：

nginx -t && nginx -s reload

步骤四：启动服务

cd ~/easyai
docker compose up -d

新增容器：easyai-pgvector（PostgreSQL）和 easyai-asg（Agent 服务治理），数据库会在首次启动时自动完成初始化和迁移。

步骤五：验证

# 检查容器状态
docker compose ps easyai-pgvector easyai-asg

# 检查 ASG 服务健康状态
curl http://127.0.0.1:3003/health

# 通过 Nginx 代理访问（配置 Nginx 后）
curl https://<你的域名>/asg-api/health

注意：如果不需要 Agent 服务治理功能，可以不执行以上步骤，不影响主服务正常运行。需要开放 3003 端口（或通过 Nginx 代理访问）。

2025.2.4

1. 增加脚本沙箱环境容器，需要更新docker-compose.yml,用以支持SKILL中的脚本运行
2. 增加环境变量配置

SANDBOX_SERVICE_BASE_URL=  #脚本运行环境使用的服务地址，默认通过 Docker 内网访问 http://sandbox:8000，不需要配置

安全默认值：Sandbox API 与 JupyterLab 不映射宿主机端口，Nginx 模板对 /api/sandbox、/sandbox、/jupyterlab 返回 404。Sandbox 使用独立 Docker 网络，不能访问 MongoDB、Redis、RabbitMQ 与治理服务。不要在公网重新开放这些高权限入口，也不要把 Sandbox 接回主业务网络。

2025.1.29

1. 优化日志管理功能，使用单独的容器和模块来进行管理，不占用主进程文件写入性能
2. Dozzle 端口默认绑定 127.0.0.1，Nginx 对 /logs-web 返回 404，禁止把容器日志查看器直接代理到公网。
3. 需要查看日志时，在受信任终端建立 SSH 隧道后访问本机端口，或直接使用 docker logs。不要依赖 Dozzle 的无认证模式或默认口令。
4. 日志下载功能默认关闭，避免容器日志被批量导出。

2025.12.27

1. 修复挂载报错问题

2025.12.26

1. 增加临时文件目录挂载，解决只读文件系统问题
2. 增加后端日志目录挂载，便于日志管理和查看

2025.12.05

1. 更新新的视频编辑容器，支持更多视频处理功能

2025.11.12

1. 删除redis内存限制配置

2025.11.11

1. 增加redis内存限制配置

2025.09.22

1. 更新配置文件中的密钥设置，用于平台对接
2. 优化docker环境变量配置，直接在docker中引入env file，避免每次都需要手动增加环境变量

2025.09.20

1. 优化redis和MQ的云端配置

2025.08.31

1. 优化nginx配置，支持插件功能

2025.08.19

1. 更新部署相关文件

2025.08.08

1. 优化部署方式为pm2，提升应用稳定性

2025.07.28

1. 增加缓存目录挂载，让nodeJS执行子进程有操作缓存的权限

2025.07.12

1. 优化docker重启策略
2. 增加minio相关配置说明

2025.07.05

1. 优化安装docker-compose的脚本，增加本地docker-compose的兜底方案
2. 兼容 docker compose 和 docker-compose 两种命令格式

2025.07.04

1. 适配新的文件上传功能
2. 增加后端文件上传目录的挂载
3. 增加二级域名的取消域名重定向注释说明

2025.06.24

1. 增加禁用文档的环境变量和配置选项

2025.06.12

1. 增加CentOS系统兼容性支持

2025.06.06

1. 删除MCP server的配置

2025.06.04

1. 删除newAPI相关配置

2025.05.26

1. 删除旧websocket MCP环境变量配置

2025.05.15

1. 优化MCP消息转发Nginx配置文件

2025.05.14

1. 删除原MCP旧配置，增加新的MCP配置
2. 修改easyai-proxy文件，删除原来旧的MCP转发，新增新的标准SSE的代理优化
3. 更新README文档

2025.05.13

1. 增加docker-compose文件

2025.03.11

1. 增加了redis的配置文件，提升了生产环境的稳定性

早期版本

1. 升级了mongoDB的数据挂载方式，使用volume挂载，避免跨平台的一些数据挂载问题
2. .env增加了版本、日志和token参数的配置

Linux/Ubuntu 一键启动

start.sh 脚本用于服务器一键安装启动EasyAI应用

首次安装部署步骤，并使用服务器公网IP进行访问

1. 克隆脚本和相关文件到服务器

git clone --depth 1 https://git.51easyai.com/wangbo/easyai.git
# 进入easyai目录
cd easyai

2. 在安全组或防火墙中仅开放 TCP 80 端口。脚本会自动生成 .env 和完整 Nginx 配置，接口统一走 /api、/socket.io、/asg-api。
3. [首次执行，后续无需重复执行]添加脚本的执行权限，命令：

chmod +x start.sh

4. 执行start.sh脚本，选择 IP 模式并输入服务器公网 IP，即可自动安装依赖、启动 EasyAI 并配置 Nginx

./start.sh

5. 脚本运行完成无错误后，打开浏览器访问 http://服务器IP。

Windows 一键启动

不要双击 start.ps1（易闪退）。在 PowerShell 中执行：

git clone --depth 1 "https://git.51easyai.com/wangbo/easyai.git" "easyai"; Set-Location "easyai"; powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1"

已在 easyai 目录内时：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1"

Windows 脚本权限说明：PowerShell 默认禁止运行脚本，直接双击 start.ps1 会闪退。

• 推荐：使用 powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\start.ps1" 执行，无需修改系统策略
• 或：以管理员身份打开 PowerShell，执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，之后可直接运行 .\start.ps1

启用 HTTPS

首次域名部署直接使用统一入口，脚本会先验证容器，再配置代理和证书，并检查 HTTPS 首页与后端就绪接口：

DEPLOY_ACCESS=domain DEPLOY_DOMAIN=demo.example.com DEPLOY_HTTPS=true \
CERTBOT_EMAIL=ops@example.com ./start.sh

已有 HTTP 站点切换 HTTPS 前，备份现有配置，按前文“后端公开 API 地址”同步公开 URL 和 WebSocket 协议，再使用 https.sh 的显式域名入口申请证书；自定义代理需要同步检查对应配置。域名解析、TCP 80/443 和证书申请均需在目标环境验收。

配置PDF图文解析Markdown功能

如果需要启用PDF图文解析Markdown功能，需要env.tools中的OSS环境变量，具体参考文件中的配置说明：自动解析PDF图文，将图片文件上传到OSS，并解析成Markdown格式，并返回

常见问题

1. 某个服务无法运行

先保留现场并查看具体服务，避免整组停机。not found / MANIFEST_UNKNOWN 表示引用的标签或摘要不存在；unauthorized / denied 需要核对镜像匿名访问权限或授权；其他服务显示 Interrupted 不能单独证明该镜像缺失。重启 Docker 或反复重试不能修复不存在的标签。

cd ~/easyai
docker compose ps
docker compose logs --tail=100 easyai-server

提供诊断信息时只附服务状态和必要错误，不要发送 .env、完整 docker compose config 或认证文件。安装和升级只有在拉取、启动、健康检查全部完成后才报告成功。

先保留故障现场，检查宿主机、容器和网络状态，再确定需要恢复的服务。Linux 启动与更新脚本会在拉取镜像前检查宿主机端口及覆盖配置中的容器地址，并自动安装常驻诊断服务（Ubuntu/Debian、systemd 环境）。诊断服务只采集证据，不自动重启业务服务。

cd easyai
sudo python3 scripts/check-deployment-resources.py
sudo systemctl status easyai-host-diagnostics atop --no-pager
sudo journalctl -b -1 -k --no-pager

服务名解析及存量部署迁移方式，日志位置、历史回放和故障排查步骤，见 部署冲突预防与宿主机诊断。先查看报错发生在端口绑定还是 Docker 网络分配阶段；不要把停止全部容器作为通用排查步骤。

Nginx 连接数不足或 MongoDB 报 Too many open files 时，可按 资源限制专项维护 更新部署仓库并执行标准维护入口；该入口保留当前镜像、数据卷和容器地址，只重载 Nginx、按需重建 MongoDB。

网页解析的公开地址、HTML 类型、长网址、时限和资源预算见 网页解析范围与资源限制。该辅助服务可以按明确的维护范围定向更新，保留主平台版本与更新偏好。

2. 启动时提示Error: listen EADDRINUSE: address already in use :::3000 端口占用，请检查端口3000是否被其他程序占用
3. invalid interpolation format for services.mongo.ports.[]. You may need to escape any with another 等关于docker-compose文件格式的报错 解决方案：docker-compose 版本太低，一般为服务器之前自己使用apt安装低版本的docker-compose，需要卸载重新安装

# 卸载docker-compose
apt remove docker-compose
#重新安装
./start.sh

4. 配置文件需要更新

使用 ./update.sh 的完整更新模式同步 Compose、脚本与配置迁移；不要只下载一个 Compose 文件替换，避免新旧脚本和变量契约混用。已有本地修改时先审查差异，再使用上面的 UPDATE_ADOPT_LEGACY_CONFIG=1 受控迁移入口。

官方模型目录

官方基础模型定义由本仓库独立维护，无需重建后端即可通过 Git 发布。维护源、公开地址、版本准备、校验和回退流程见 官方模型目录。平台后端和独立 AI Gateway 只读消费；不再使用原 OSS/CDN 目录发布流程。