r
315 lines
8.7 KiB
Markdown
315 lines
8.7 KiB
Markdown
# Nexus 项目说明文档（2026-07-08）
|
||
|
||
## 1. 项目定位
|
||
|
||
Nexus 是一个服务器资产管理、远程运维、宝塔面板管理和自动化发布平台。当前重点能力包括：
|
||
|
||
- 服务器资产管理；
|
||
- SSH / WebSSH / 文件管理；
|
||
- 批量脚本执行；
|
||
- 宝塔面板一键登录；
|
||
- 宝塔 Session TTL 自动检测与修复；
|
||
- 审计日志与安全巡检；
|
||
- 旧后台 `/app/` 与新后台 `/app-v2/` 双后台并行；
|
||
- 发布包制品化与 Gitea / Act Runner 自动发布方向。
|
||
|
||
## 2. 当前项目路径
|
||
|
||
源码快照目录：
|
||
|
||
```text
|
||
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\work\nexus_code_context\snapshots\nexus-source-20260707-112042
|
||
```
|
||
|
||
发布文档目录：
|
||
|
||
```text
|
||
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs
|
||
```
|
||
|
||
最新发布包：
|
||
|
||
```text
|
||
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz
|
||
```
|
||
|
||
SHA256：
|
||
|
||
```text
|
||
46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b
|
||
```
|
||
|
||
## 3. 技术栈概览
|
||
|
||
### 后端
|
||
|
||
- Python / FastAPI 风格 API；
|
||
- SQLAlchemy；
|
||
- Redis；
|
||
- SSH / Paramiko 相关远程能力；
|
||
- Docker / 1Panel 部署脚本；
|
||
- 宝塔 API + SSH bootstrap 混合修复链路。
|
||
|
||
### 前端
|
||
|
||
旧后台：
|
||
|
||
```text
|
||
web/app/
|
||
```
|
||
|
||
新后台：
|
||
|
||
```text
|
||
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. 重要目录说明
|
||
|
||
```text
|
||
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、并发锁等场景。
|
||
|
||
关键文件：
|
||
|
||
```text
|
||
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 只显示“已配置/未配置”，不显示真实值；
|
||
- 前端构建产物有敏感扫描。
|
||
|
||
关键文件：
|
||
|
||
```text
|
||
frontend-v2/
|
||
web/app-v2/
|
||
frontend-v2/scripts/scan-app-v2-sensitive.mjs
|
||
server/main.py
|
||
Dockerfile
|
||
Dockerfile.prod
|
||
```
|
||
|
||
### 5.3 发布制品化
|
||
|
||
当前发布不再只靠零散文件复制，而是生成完整 tar.gz 发布包。
|
||
|
||
关键脚本：
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
服务器侧脚本：
|
||
|
||
```text
|
||
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 测试：
|
||
|
||
```text
|
||
65 passed
|
||
```
|
||
|
||
发布包验证：
|
||
|
||
- tarball scan 通过；
|
||
- `apply-release-bundle.sh --validate-only` 通过；
|
||
- metadata / `.sha256` / tar 实际 SHA 一致；
|
||
- 不包含 `tmp/pytest-publish-release`；
|
||
- 不包含高置信真实敏感信息。
|
||
|
||
## 7. 发布方式
|
||
|
||
### 7.1 当前推荐：发布包方式
|
||
|
||
发布包：
|
||
|
||
```text
|
||
C:\Users\uzuma\Documents\Codex\2026-07-06\yuu\outputs\nexus-release-20260708.tar.gz
|
||
```
|
||
|
||
SHA256：
|
||
|
||
```text
|
||
46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b
|
||
```
|
||
|
||
只上传并执行 preflight：
|
||
|
||
```cmd
|
||
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 没问题后正式发布：
|
||
|
||
```cmd
|
||
.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 仓库：
|
||
|
||
```text
|
||
http://66.154.115.8:3000/admin/Nexus.git
|
||
```
|
||
|
||
如果要用局域网机器 `192.168.124.219` 做新的代码托管平台，建议安装：
|
||
|
||
```text
|
||
Gitea + Act Runner
|
||
```
|
||
|
||
含义：
|
||
|
||
- Gitea：代码仓库、分支、Web 管理；
|
||
- Act Runner：执行 Gitea Actions / CI/CD / 自动发布。
|
||
|
||
推荐最终流程：
|
||
|
||
```text
|
||
开发机 / Codex
|
||
-> git push 到 Gitea
|
||
-> Gitea Actions 触发
|
||
-> Act Runner 跑 gate / 打包
|
||
-> SSH 到正式服务器
|
||
-> apply-release-bundle.sh 发布
|
||
-> 验证 /health /app/ /app-v2/
|
||
```
|
||
|
||
第一次建议先做手动触发或 release 分支触发，不要一 push 就直接发布生产。
|
||
|
||
## 8. 测试部署机说明
|
||
|
||
局域网测试部署机：
|
||
|
||
```text
|
||
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. 重要文档索引
|
||
|
||
```text
|
||
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 发布。
|
||
|