admin/Nexus
1
0
Fork 0
Code Issues Pull Requests Actions 85 Packages Projects Releases Wiki Activity
Files
9b583ccc9148b1ab962549a5cc440ecb357596c4
Nexus/docs/release/20260708/Nexus-项目说明文档-20260708.md
T
r 9b583ccc91
Nexus CI/CD / test (push) Waiting to run
Details
Nexus CI/CD / e2e (push) Blocked by required conditions
Details
Nexus CI/CD / deploy (push) Blocked by required conditions
Details
Nexus Pre-commit Checks / quick-check (push) Waiting to run
Details
docs(release): 主与 release 分支合并功能清单 + 导入 release 文档目录 
便于 Gitea 上 main ↔ release/20260708-axs 合并评审与冲突对照。
2026-07-09 01:14:32 +08:00

8.7 KiB
Raw Blame History

Nexus 项目说明文档（2026-07-08）

1. 项目定位

Nexus 是一个服务器资产管理、远程运维、宝塔面板管理和自动化发布平台。当前重点能力包括：

  • 服务器资产管理；
  • SSH / WebSSH / 文件管理；
  • 批量脚本执行；
  • 宝塔面板一键登录；
  • 宝塔 Session TTL 自动检测与修复；
  • 审计日志与安全巡检；
  • 旧后台 /app/ 与新后台 /app-v2/ 双后台并行；
  • 发布包制品化与 Gitea / Act Runner 自动发布方向。

2. 当前项目路径

源码快照目录：

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\outputs

最新发布包：

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

SHA256：

46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b

3. 技术栈概览

后端

  • Python / FastAPI 风格 API；
  • SQLAlchemy；
  • Redis；
  • SSH / Paramiko 相关远程能力；
  • Docker / 1Panel 部署脚本；
  • 宝塔 API + SSH bootstrap 混合修复链路。

前端

旧后台：

web/app/

新后台：

frontend-v2/
web/app-v2/

新后台技术栈：

  • React；
  • TypeScript；
  • Vite；
  • Tailwind / shadcn 风格组件；
  • TanStack Query；
  • TanStack Table；
  • Zustand。

部署/发布

  • Docker / 1Panel；
  • deploy/apply-release-bundle.sh；
  • deploy/preflight-release-host.sh；
  • scripts/prepare_release_artifact.py；
  • scripts/publish_release_bundle.py。

4. 重要目录说明

server/                         后端 API、服务、基础设施代码
server/api/                     FastAPI 路由层
server/application/services/    业务服务层
server/infrastructure/          Redis、SSH、宝塔等基础设施封装
frontend-v2/                    新后台源码
web/app/                        旧后台静态产物
web/app-v2/                     新后台静态产物
deploy/                         部署、升级、回滚、1Panel 脚本
scripts/                        本地 gate、打包、发布辅助脚本
tests/                          后端和发布辅助脚本测试
outputs/                        本轮审查、发布、说明文档

5. 当前核心改动

5.1 宝塔长期不掉线修复

问题根因：部分宝塔版本 task.py 中硬编码 3600 秒清理 tmp_login session，导致 Nexus 一键登录后 1～2 小时刷新掉线。

当前修复方向：

  • 登录前自动检测/修复宝塔 hardcoded 3600；
  • 改为基于 public.get_session_timeout() 或默认 86400；
  • 新增 Redis 分布式锁，避免同一宝塔并发签发 login URL 时 tmp_token 互相覆盖；
  • SSH bootstrap 增加远端 flock / mktemp / atomic replace；
  • 新增测试覆盖宝塔登录、TTL、bootstrap、并发锁等场景。

关键文件：

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

5.2 /app-v2 第二后台

新增第二后台 /app-v2/，与旧后台 /app/ 并行，方便逐步替换旧后台。

关键特性：

  • 更现代的 UI；
  • 响应更快；
  • 保留原功能入口；
  • 敏感信息不展示；
  • 全局 API Key 只显示“已配置/未配置”，不显示真实值；
  • 前端构建产物有敏感扫描。

关键文件：

frontend-v2/
web/app-v2/
frontend-v2/scripts/scan-app-v2-sensitive.mjs
server/main.py
Dockerfile
Dockerfile.prod

5.3 发布制品化

当前发布不再只靠零散文件复制，而是生成完整 tar.gz 发布包。

关键脚本：

scripts/prepare_release_artifact.py        一键本地 gate + manifest + tar.gz + scan + metadata + validate-only
scripts/generate_release_bundle.py         生成干净发布包
scripts/scan_release_bundle.py             扫描发布包是否含敏感/脏文件
scripts/write_release_metadata.py          写 metadata 和 .sha256
scripts/publish_release_bundle.py          Python 版上传 + preflight + 可选 apply
scripts/check_text_integrity.py            检查 UTF-8 / 控制字符 / Markdown fence

服务器侧脚本：

deploy/preflight-release-host.sh           服务器发布前检查
deploy/apply-release-bundle.sh             校验、备份、应用发布包、重建、验证
deploy/sync_webapp_to_container.sh         同步 /app 与 /app-v2 静态资源到容器

6. 当前验证状态

本地 release gate 已通过：

  • Python 编译检查；
  • deploy shell bash -n；
  • deploy excludes 检查；
  • 文本完整性检查；
  • /app-v2 build:safe；
  • app-v2 敏感扫描；
  • 宝塔专项测试 60 个；
  • 发布辅助脚本测试 5 个。

合计 Python 测试：

65 passed

发布包验证：

  • tarball scan 通过；
  • apply-release-bundle.sh --validate-only 通过；
  • metadata / .sha256 / tar 实际 SHA 一致；
  • 不包含 tmp/pytest-publish-release；
  • 不包含高置信真实敏感信息。

7. 发布方式

7.1 当前推荐：发布包方式

发布包：

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

SHA256：

46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b

只上传并执行 preflight：

cd /d C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042
.venv-py312-codex\Scripts\python.exe scripts\publish_release_bundle.py ^
  --remote nexus ^
  --tarball C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs
exus-release-20260708.tar.gz ^
  --sha256 46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b

确认 preflight 没问题后正式发布：

.venv-py312-codex\Scripts\python.exe scripts\publish_release_bundle.py ^
  --remote nexus ^
  --tarball C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs
exus-release-20260708.tar.gz ^
  --sha256 46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b ^
  --apply

7.2 Gitea 发布方向

已有远端 Gitea 仓库：

http://66.154.115.8:3000/admin/Nexus.git

如果要用局域网机器 192.168.124.219 做新的代码托管平台，建议安装：

Gitea + Act Runner

含义：

  • Gitea：代码仓库、分支、Web 管理；
  • Act Runner：执行 Gitea Actions / CI/CD / 自动发布。

推荐最终流程：

开发机 / Codex
  -> git push 到 Gitea
  -> Gitea Actions 触发
  -> Act Runner 跑 gate / 打包
  -> SSH 到正式服务器
  -> apply-release-bundle.sh 发布
  -> 验证 /health /app/ /app-v2/

第一次建议先做手动触发或 release 分支触发，不要一 push 就直接发布生产。

8. 测试部署机说明

局域网测试部署机：

192.168.124.219

已知用途：

  • Nexus 测试部署机；
  • Web 入口曾记录为：http://192.168.124.219:18600/app/；
  • 本地 Git 工作树：/opt/nexus-dev-current；
  • 曾用于 pytest、代码上下文索引、Zvec 部署等。

当前记录显示：它有本地 Git 仓库/工作树，但没有明确证据表明已安装 Gitea 服务。

9. 安全注意事项

  1. 不要提交 .env、私钥、真实 token、宝塔 key、数据库密码；
  2. 发布包已排除 .env、docker/.env.prod、web/data、venv、node_modules、缓存等；
  3. /app-v2 不显示全局 API Key；
  4. 宝塔一键登录必须走后端接口，不在前端生成 tmp token；
  5. script_service 是管理员远程执行命令功能，属于产品能力，不按普通漏洞处理；
  6. Gitea Actions 如要生产发布，必须先配置好 Secrets 和最小权限 SSH Key。

10. 重要文档索引

C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-release-index-20260708.md
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-release-ready-checklist-20260708.md
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-manual-deploy-commands-20260708.md
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-release-python-publisher-20260708.md
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-release-publisher-tests-20260708.md
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-app-v2-双后台实施说明-20260707.md
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\Nexus-API服务数据库调用链索引报告-20260707.md

11. 当前未完成事项

  • 线上 https://api.synaglobal.vip 尚未由 Codex 亲自完成 SSH 发布验证；
  • 原因是本线程仍使用 auto_review 审批，当前 CC Switch 不支持 codex-auto-review；
  • 用户可手动执行发布命令，或改用 Gitea/Act Runner 发布。
Reference in New Issue View Git Blame Copy Permalink