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
+20
View File
@@ -1,19 +1,28 @@
#!/usr/bin/env bash
# 远程 runner 的数据库/集成检查,会编译测试二进制并运行容器;不能在未授权本地环境执行。
set -euo pipefail
# 随机隔离数据库容器不映射宿主端口,EXIT 时销毁;trust 认证只用于该临时网络命名空间。
# 在调用前应位于仓库根目录,db/、internal/ 和 bin/ 的相对路径都以该位置解析。
# 参数和真实生产配置不参与本次测试,生成随机容器名,避免并行检查互相复用数据库。
container=foundry-schema-$(openssl rand -hex 8)
cleanup() { docker rm -f "$container" >/dev/null 2>&1 || true; }
trap cleanup EXIT
# No host port or shared network. The database is discarded after this check.
docker run -d --name "$container" --network none \
-e POSTGRES_HOST_AUTH_METHOD=trust postgres:17-alpine >/dev/null
# 最多等待约三十秒;循环结束不单独宣告就绪,后续 psql 仍会在数据库不可用时失败。
for attempt in {1..30}; do
if docker exec "$container" pg_isready -h 127.0.0.1 -U postgres >/dev/null 2>&1; then break; fi
sleep 1
done
# 通过 docker exec 进入隔离容器执行 psql;ON_ERROR_STOP 保证 SQL 断言失败立即终止脚本。
psql() { docker exec -i "$container" psql -X -U postgres -v ON_ERROR_STOP=1; }
# 先安装最早认证版本并植入有效/过期旧会话,模拟部署前已有用户数据。
psql < db/001-auth.sql
psql <<'SQL'
@@ -23,12 +32,16 @@ INSERT INTO project_sessions VALUES
('existing-session','fixture','00000000-0000-0000-0000-000000000001',now()+interval '1 hour'),
('expired-session','fixture','00000000-0000-0000-0000-000000000001',now()-interval '1 hour');
SQL
# 运行角色只用于隔离测试;迁移器随后为它授予应用权限,用它检查应用而不是始终使用 postgres 超级用户。
psql <<'SQLROLE'
CREATE ROLE foundry_fixture LOGIN;
SQLROLE
# 连续跑两次真实迁移器,验证旧基线接管和校验和重放,而不是仅验证全新数据库建表。
python3 deploy/migrate.py --container "$container" --database postgres --role foundry_fixture
python3 deploy/migrate.py --container "$container" --database postgres --role foundry_fixture
# SQL 断言旧 Google 绑定保留、过期会话不复活、绝对期限添加,再在回滚事务中验证资源与跨项目外键。
psql <<'SQL'
DO $$
@@ -72,8 +85,13 @@ END $$;
ROLLBACK;
SQL
printf 'Migration preserved existing logins and enforced project isolation.\n'
# 安装研究库测试语料及只读角色,随后各 Go 包按各自数据库环境变量运行集成用例。
psql < internal/research/testdata/corpus.sql
# runner 编译 Linux 静态测试程序,随后在同数据库网络空间用最小权限容器运行,源码不挂入测试容器。
# go test -c 只生成测试可执行文件;真正运行在后面的容器中,不是重复在 runner 上跑一次测试。
# --network container:... 共用临时数据库的网络命名空间,所以测试里的 127.0.0.1 指向该临时数据库。
for package in platform auth research; do
CGO_ENABLED=0 go test -mod=readonly -c -o "bin/$package-tests" "./internal/$package"
docker run --rm --network "container:$container" --user 1000:1000 \
@@ -88,6 +106,8 @@ done
# Run the actual pinned Endoleap runtime against this build's authenticated HTTP
# routes and the same disposable database. Only this remote container needs Node.
# 可选 pinned Endoleap 客户端需要 Node,额外运行一次真实 HTTP 客户端集成;未提供时跳过该阶段。
# HEADLESS_CLIENT_SOURCE 应由 CI 指向固定提交的前端源码;本脚本只验证已有路径,不自行下载最新版。
# 这一阶段用真实 HTTP handler 与 headless 客户端验证协议,不能替代生产账号或线上部署验收。
if [[ -n "${HEADLESS_CLIENT_SOURCE:-}" ]]; then
test -f "$HEADLESS_CLIENT_SOURCE/tests/headless/foundry.integration.mjs"
docker run --rm --network "container:$container" --user 1000:1000 \