docs: explain deployment stages and separate comment sections [skip ci]

This commit is contained in:
2026-11-17 00:01:26 +08:00
parent 00fd89af1a
commit 53bc8d73eb
7 changed files with 123 additions and 0 deletions
+34
View File
@@ -1,9 +1,13 @@
#!/usr/bin/env bash
# 由 main 部署工作流在远程基础设施主机执行,参数一必须是已构建的 Foundry 二进制。
# 本脚本会迁移数据库、替换 worker 并启动候选服务,不能当作本地静态检查执行。
# -e 遇未处理失败退出,-u 拒绝未定义变量,pipefail 让管道任一失败可见;umask 限制新建配置文件权限。
set -euo pipefail
umask 077
# 本脚本依赖远程基础设施目录和已存在的 Docker 网络,不负责构建二进制或创建整套基础设施。
# origin 是外部 HTTPS 地址,candidate 是切流前的临时容器名,network 供 Core 访问数据库/反向代理。
base=/opt/endoleap-infra
foundry=$base/foundry
origin=https://api.foundry.entroia.com
@@ -18,6 +22,7 @@ for name in GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET; do
exit 1
fi
done
# Accept formatted JSON from Actions Variables and never print its contents.
# 将 Actions 中可多行排版的 JSON 压为单行;这里只校验映射形状,URL 协议由服务启动继续验证。
FOUNDRY_PROJECTS=$(python3 - <<'PYCONFIG'
@@ -40,21 +45,29 @@ if not isinstance(projects, dict) or not projects or any(
print(json.dumps(projects, separators=(",", ":")))
PYCONFIG
)
# 上面的 Python 只在子进程中整理 JSON;export 让后续容器从当前进程环境取得规范化结果。
export FOUNDRY_PROJECTS
# database.env 由服务器预置并保存数据库连接信息;这里只检查存在,不能把凭据写入源码或日志。
test -s "$foundry/database.env"
# Go's HTTPS client uses the OS trust store, not Node's bundled roots.
# The slim Node runtime has no system CA bundle of its own.
ca_bundle=/etc/ssl/certs/ca-certificates.crt
test -s "$ca_bundle"
docker network inspect "$network" >/dev/null
# 先运行全事务迁移及角色授权,迁移失败立即终止,不让新服务在半升级 schema 上启动。
python3 "$(dirname "$0")/migrate.py"
# 每次发布使用独立二进制目录供只读挂载;本脚本不清除旧 release 目录。
release=$(mktemp -d "$foundry/release.XXXXXXXX")
install -m 755 "$1" "$release/foundry"
# 容器内监听全部接口供同网络的代理访问;端口 8080 没有在此发布到宿主公网,TLS 由 Traefik 处理。
export HOST=0.0.0.0 PORT=8080 PUBLIC_ORIGIN="$origin"
# 邮件/研究配置可选且从受保护文件加载;Slack 优先 Actions 环境,缺省才回退服务器文件。
mail_env=()
if [[ -s "$foundry/mail.env" ]]; then
@@ -78,18 +91,27 @@ if [[ -n "${SLACK_CLIENT_ID:-}" || -n "${SLACK_CLIENT_SECRET:-}" ]]; then
elif [[ -s "$foundry/slack.env" ]]; then
slack_env=(--env-file "$foundry/slack.env")
fi
# 下面构造可选 IPC 挂载参数;未配置 worker 时数组为空,Core 仍可启动其余业务接口。
codex_mounts=()
codex_dir=$foundry/codex
# 存在 worker 配置才启用 IPC;worker 必须先与当前 Core 二进制协议对齐,启动失败恢复旧 worker。
if [[ -d "$codex_dir" ]]; then
# Core and its private worker must speak the same Canvas artifact protocol.
# Keep the previous container definition for exact startup rollback.
# 保留旧容器本身,确保新 worker 启动/目录检查失败时可以恢复原来的挂载和配置。
# 这里先停旧 worker 再启动新 worker,替换期间并非双 worker 无缝接管。
worker_backup=
if docker inspect foundry-codex-worker >/dev/null 2>&1; then
worker_backup=foundry-codex-worker-previous-$(date +%s)-$$
docker stop -t 5 foundry-codex-worker >/dev/null
docker rename foundry-codex-worker "$worker_backup"
fi
# 用当前 release 的同一份 Go 二进制启动 worker,避免 Core/worker 的画布产物协议不一致。
# 目录探测只验证 socket 和非空模型目录,不执行一次真实生成,也不验证模型账户额度。
worker_ready=false
if bash "$(dirname "$0")/codex-worker.sh" "$release/foundry" >/dev/null; then
for attempt in {1..20}; do
@@ -115,6 +137,7 @@ if [[ -d "$codex_dir" ]]; then
printf 'Canvas worker startup/catalog verification failed; previous worker restored.\n' >&2
exit 1
fi
# 目录探测成功后删除旧 worker 定义;后续候选/路由失败不会再恢复该 worker,回滚范围需据此理解。
if [[ -n "$worker_backup" ]]; then docker rm "$worker_backup" >/dev/null; fi
for attempt in {1..20}; do
@@ -123,6 +146,9 @@ if [[ -d "$codex_dir" ]]; then
done
test -S "$codex_dir/run/worker.sock"
test -s "$codex_dir/grants/projects.json"
# API 容器只拿 socket 和项目授权表;只读目录挂载允许连接 socket,但禁止修改目录内容。
# 这不把 worker 的 CLI 登录目录提供给 Core,两个进程仍使用各自的文件系统与环境。
codex_mounts=(
--mount "type=bind,source=$codex_dir/run,target=/run/foundry-codex,readonly"
--mount "type=bind,source=$codex_dir/grants,target=/etc/foundry-codex,readonly"
@@ -131,6 +157,8 @@ if [[ -d "$codex_dir" ]]; then
)
fi
# 使用现成 node 镜像作为运行载体,实际启动 /opt/foundry 这个 Go 可执行文件,不在此 docker build。
# Node 供就绪探测使用;CA bundle 供 Go 的 HTTPS 客户端使用,二者的证书来源不能混为一谈。
# Core 只挂载 IPC/授权表,不挂载 CLI 登录;以非 root、只读根文件系统和裁剪能力运行。
docker run -d --name "$candidate" "${codex_mounts[@]}" "${mail_env[@]}" "${slack_env[@]}" "${research_env[@]}" --network "$network" \
--env-file "$foundry/database.env" -e HOST -e PORT -e PUBLIC_ORIGIN \
@@ -146,6 +174,8 @@ docker run -d --name "$candidate" "${codex_mounts[@]}" "${mail_env[@]}" "${slack
cleanup_candidate() {
docker rm -f "${live:-$candidate}" >/dev/null 2>&1 || true
}
# 从候选 Core 启动后的阶段安装清理器;后续检查失败会移除本次 Core,不能据此推断前面的迁移/worker 也回滚。
trap cleanup_candidate EXIT
# 容器内 smoke 只验证 CA 文件、数据库就绪及匿名请求被拒,不执行真实 OAuth 或付费模型。
@@ -182,7 +212,11 @@ docker exec "$candidate" node -e '
id=$(docker inspect -f '{{.Id}}' "$candidate")
live=foundry-core-${id:0:12}
docker rename "$candidate" "$live"
# 只有候选内部检查通过才设为长期容器并请求切流;重启策略保证 Docker 重启后继续运行。
docker update --restart unless-stopped "$live" >/dev/null
bash "$(dirname "$0")/route.sh" "$live"
# route.sh 成功返回后解除本脚本的候选清理,保留新 Core;旧 release 目录仍由单独运维策略管理。
trap - EXIT
printf 'Foundry readiness and unauthenticated rejection verified.\n'