Nexus/docs/release/20260708/Nexus-release-ready-checklist-20260708.md

Nexus 发布前清单（2026-07-08）

结论

当前本地快照已经通过完整发布前 Gate：

py_compile + /app-v2 build:safe + app-v2 sensitive scan + 宝塔 pytest

最终结果：

[release-gate] OK
60 passed in 5.33s

当前源码快照

C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042

对比基准快照：

C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-070236

完整差异清单：

C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-release-diff-manifest-20260708.md

差异清单汇总

重新生成后的清单已经排除：

• .git
• node_modules
• .venv-*
• venv
• __pycache__
• .ruff_cache
• .playwright-mcp
• .cursor
• .pytest_cache
• *.pyc
• *.pyo
• *.bak-
• 2025.2
• =2025.2
• tmp/nexus-frontend.tar.gz

当前差异统计：

added=381
modified=26
deleted=347

注意：差异里包含大量旧 /app/ 静态构建产物变动。如果只发布本轮宝塔稳定性与 /app-v2，可以优先发布“核心发布集合”，不要盲目同步整个快照目录。

核心发布集合

后端宝塔一键登录稳定性

server/application/services/btpanel_service.py
server/infrastructure/btpanel/bootstrap_lock.py
server/infrastructure/btpanel/login_url_lock.py
server/infrastructure/btpanel/ssh_bootstrap.py
server/main.py

API / 服务相关历史改动

差异清单中还有以下后端文件发生变化，发布前需要按实际范围确认是否一起发布：

server/api/assets.py
server/api/scripts.py
server/api/sync_v2.py
server/application/services/server_file_transfer_service.py
server/infrastructure/ssh/remote_archive.py
server/utils/files_chmod_policy.py

这些文件属于此前安全巡检/文件传输/脚本执行相关改动，不是本轮宝塔一键登录最小集合；如果线上已经发布过，可跳过或只按 diff 覆盖。

/app-v2 双后台

源码：

frontend-v2/

构建产物：

web/app-v2/

后端静态挂载：

server/main.py

Docker：

Dockerfile
Dockerfile.prod

测试与发布脚本

requirements-dev.txt
scripts/check_backend_test_env.py
scripts/generate_release_diff.py
scripts/run_btpanel_tests.py
scripts/run_btpanel_tests_docker.cmd
scripts/run_btpanel_tests_docker.sh
scripts/run_local_release_gate.py
scripts/scan_release_manifest.py

测试文件

tests/test_btpanel_bootstrap_lock.py
tests/test_btpanel_get_config.py
tests/test_btpanel_login_url.py
tests/test_btpanel_login_url_route.py
tests/test_btpanel_ssh_bootstrap.py

发布前验证命令

1. 重新生成差异清单

.venv-py312-codex\Scripts\python.exe scripts\generate_release_diff.py --old C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-070236 --new C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042 --output C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-release-diff-manifest-20260708.md

结果：

added=369 modified=21 deleted=347

2. 扫描发布候选文件是否包含已知环境泄露标记

.venv-py312-codex\Scripts\python.exe scripts\scan_release_manifest.py --root C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042 --manifest C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-release-diff-manifest-20260708.md

结果：

OK: no known environment leak markers found in release manifest entries

3. 完整发布前 Gate

.venv-py312-codex\Scripts\python.exe scripts\run_local_release_gate.py --with-pytest

结果：

[app-v2-sensitive-scan] OK: scanned 9 file(s), no high-confidence secrets found
collected 60 items
60 passed in 1.79s
[release-gate] OK

最新 Gate 追加确认：

bash -n deploy/sync_webapp_to_container.sh
60 passed in 1.70s
[release-gate] OK

4. 生成干净发布包

.venv-py312-codex\Scripts\python.exe scripts\generate_release_bundle.py --root C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042 --output C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz

结果：

files=2409

发布包位置：

C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz

发布包元数据：

C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.metadata.json
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-release-artifact-metadata-20260708.md

SHA256：

46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b

5. 扫描发布包

.venv-py312-codex\Scripts\python.exe scripts\scan_release_bundle.py C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz

结果：

size_mb=27.02
entries=2409
OK: release bundle looks clean

6. 部署排除规则自检

scripts/run_local_release_gate.py 现在会自动执行：

.venv-py312-codex\Scripts\python.exe scripts\check_deploy_excludes.py

结果：

OK: deploy exclusion patterns are present

7. 发布后线上验证脚本

新增：

scripts/verify_online_release.py

用途：

• 检查 /health
• 检查旧后台 /app/
• 检查新后台 /app-v2/
• 检查页面里不要出现 全局 API Key、Global API Key、tmp_login、tmp_token

发布后执行：

.venv-py312-codex\Scripts\python.exe scripts\verify_online_release.py --base-url https://api.synaglobal.vip

明确不发布

以下内容不要同步到正式服务器：

.venv-py312-codex/
.venv-py314/
venv/
frontend-v2/node_modules/
.pytest_cache/
__pycache__/
.ruff_cache/
.cursor/
.playwright-mcp/
frontend-v2/node_modules/
*.pyc
*.pyo
*.bak-
2025.2
=2025.2
tmp/nexus-frontend.tar.gz

其中 2025.2 / =2025.2 是 Windows CMD 执行 tzdata>=2025.2 时可能产生的重定向误文件，绝对不要发布。

建议发布顺序

方案 A：Docker 镜像重建发布（推荐）

1. 使用当前快照作为构建上下文，但确保 .dockerignore 排除虚拟环境、node_modules、缓存和临时文件。
2. 构建生产镜像。
3. 启动新容器前备份旧容器镜像/tag 和数据库。
4. 发布后执行线上验证。

优点：静态资源、后端代码、依赖环境一致性更好。

当前已修复：

• .dockerignore 已排除 frontend-v2/node_modules、.venv-*、.pytest_cache、2025.2、*.bak- 等。
• deploy/rsync-local-to-server.sh 已排除 frontend-v2/node_modules、.venv-*、.pytest_cache、2025.2、*.bak- 等。
• scripts/run_local_release_gate.py 已增加 bash -n 检查 deploy/deploy-production.sh 与 deploy/rsync-local-to-server.sh。
• deploy/deploy-production.sh 发布后健康检查已增加 /app-v2/。
• deploy/deploy-production.sh 已显式构建并上传 web/app-v2，不只依赖 Dockerfile 构建。
• deploy/apply-release-bundle.sh 已新增，可在服务器侧对 tar.gz 发布包执行 SHA256 校验、备份、解包、重建和本机验证。
• deploy/sync_webapp_to_container.sh 已同步 web/app-v2 到容器，并校验 /app-v2/ 主 bundle。
• scripts/run_local_release_gate.py 已增加 bash -n deploy/sync_webapp_to_container.sh。
• scripts/check_deploy_excludes.py 会防止发布排除规则未来被误删。

当前远程执行状态

本轮尝试对线上 Host nexus 做只读 SSH 探测时，Codex 审批系统返回 404 并拒绝执行。不是 SSH 凭据或代码错误，而是自动审批代理不可用。

因此本轮没有实际修改线上服务器。当前状态是：

本地发布包：已生成
发布包扫描：通过
完整 release gate：通过
线上部署：尚未执行

如果要由 Codex 继续实际发布，需要在下一步明确允许 SSH 发布操作。

手动发布命令清单

已生成：

C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-manual-deploy-commands-20260708.md

该文档包含：

• deploy/deploy-production.sh 一键发布方式。
• tar.gz 发布包上传方式。
• 线上 SHA256 校验。
• 线上备份、解包、Docker 重建。
• 发布后 /health、/app/、/app-v2/ 验证。
• 宝塔专项验证。
• 回滚命令。

最新最终验证

发布包扫描：

size_mb=27.02
entries=2409
OK: release bundle looks clean

完整 Gate：

60 passed in 1.70s
[release-gate] OK

方案 B：只同步核心文件到现有线上目录

适合快速热修：

1. 同步后端核心文件。
2. 同步 web/app-v2/。
3. 重启后端服务。
4. 验证宝塔一键登录和 /app-v2/。

缺点：如果线上依赖、静态目录或 Dockerfile 状态与本地不一致，容易遗漏。

线上验证清单

发布到：

https://api.synaglobal.vip

后验证：

1. /app/ 旧后台仍可访问。
2. /app-v2/ 新后台可访问。
3. /api/btpanel/servers/{id}/login-url 正常返回登录地址。
4. 同一台宝塔短时间重复点一键登录，应该只允许一个签发流程，冲突时返回 HTTP 409。
5. 新增宝塔或配置缺失宝塔，在一键登录前会触发 session cleanup TTL 兜底检测/修复。
6. 多台宝塔同时打开，2 小时后刷新不应因为 task.py hardcoded_3600 陆续掉线。
7. 线上页面不显示全局 API Key 明文。

回滚点

发布前建议备份：

server/application/services/btpanel_service.py
server/infrastructure/btpanel/bootstrap_lock.py
server/infrastructure/btpanel/login_url_lock.py
server/infrastructure/btpanel/ssh_bootstrap.py
server/main.py
web/app-v2/
Dockerfile
Dockerfile.prod

如果发布后宝塔一键登录异常：

1. 先回滚上述后端文件。
2. 重启后端服务。
3. 保留 /app-v2/ 不影响旧 /app/，必要时可以只移除 web/app-v2/ 静态目录或取消 server/main.py 挂载。

2026-07-08 validate-only verification

The server-side release applier now supports validate-only mode.

Command verified locally with Git Bash:

bash deploy/apply-release-bundle.sh --validate-only --tarball /c/Users/uzuma/Documents/Codex/2026-07-06/yuu/outputs/nexus-release-20260708.tar.gz --sha256 46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b
`

Result:

`	ext
SHA256 OK: 46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b
Extracted release tree validation OK
Validate-only mode: tarball checksum and content validation passed
`

Network/SSH production execution is still not performed because Codex approval auto-review returned HTTP 404 for read-only checks.


## 2026-07-08 one-command local artifact preparation

A single local command now prepares and verifies the release artifact end-to-end:

`cmd
.venv-py312-codex\Scripts\python.exe scripts\prepare_release_artifact.py --old-snapshot C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-070236 --output-dir C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs --name nexus-release-20260708
`

Verified result:

`	ext
[prepare-release-artifact] OK
added=381 modified=26 deleted=347
files=2409
entries=2409
size_mb=27.02
sha256=46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b
60 passed in 1.70s
`


## 2026-07-08 release index and checksum file

Release index:

`	ext
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-release-index-20260708.md
`

Standard SHA256 checksum file:

`	ext
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz.sha256
`

The checksum file contains:

`	ext
46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b  nexus-release-20260708.tar.gz
`


## Server preflight command

Before applying the release on the production host, run:

```bash
bash /tmp/nexus-release/deploy/preflight-release-host.sh \
  --tarball /tmp/nexus-release-20260708.tar.gz \
  --sha256 46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b \
  --deploy-path /opt/nexus

This checks required commands, checksum, release tar paths, deploy path, runtime hints, disk space, and current local endpoints before applying changes.