Nexus/docs/release/20260708/PR-MERGE-main与release合并清单-20260709.md

# Nexus 分支合并清单：`main` ↔ `release/20260708-axs`

> **编写日期**：2026-07-09  
> **用途**：合并评审 / Gitea PR 描述 / 冲突解决对照表  
> **Gitea**：https://axs.kuma1xn.vip/admin/Nexus

---

## 1. 两分支现状

| 分支 | 提交 | 说明 |
|------|------|------|
| **`main`** | `5520434d` | 主项目全量历史（598 提交）；含运维侧 6～7 月功能 + **一键登录 bootstrap→SSH 回退** |
| **`release/20260708-axs`** | `74149e0d` | 发布快照（孤儿 squash）；含 **宝塔 Session 1～2h 掉线修复** + **`/app-v2`** + 发布制品链 |

两分支 **无共同祖先**，不能普通 fast-forward，需 `--allow-unrelated-histories` 或按模块 cherry-pick。

**推荐合并方向**：`release/20260708-axs` → `main`（保留 main 历史，吸收 release 独有能力）。

```bash
cd /path/to/Nexus
git fetch https://axs.kuma1xn.vip/admin/Nexus.git main release/20260708-axs
git checkout main
git merge FETCH_HEAD:release/20260708-axs -m "merge: release/20260708-axs 宝塔 Session + app-v2" --allow-unrelated-histories
```

---

## 2. `main` 已有、合并时需保留的功能

### 2.1 宝塔一键登录：bootstrap 失败恢复 SSH 回退（2026-07-08 · 运维侧）

**问题**：2026-06-21「自动 bootstrap」后，新机 API 未就绪时 bootstrap 失败直接 `raise`，不再走 SSH `tools.py`，一键登录整链中断。

**行为**：

- 未配置 API 时仍先 `source=immediate` bootstrap（best-effort）
- 非凭据类错误（`ssh_command_failed`、`bt_not_installed` 等）→ **继续 SSH 临时登录**
- 仅 `ssh_auth_failed` / `ssh_no_credentials` / `ssh_sudo_required` / `missing_center_ip` 硬中断

**关键代码**：

| 文件 | 要点 |
|------|------|
| `server/application/services/btpanel_service.py` | `BOOTSTRAP_LOGIN_HARD_FAIL_ERRORS`、`_create_login_url_fresh` |
| `server/infrastructure/btpanel/ssh_bootstrap.py` | 检测 `class/common.py`（非空 panel 目录）；写 `api.json` 前 `makedirs` config |
| `tests/test_btpanel_login_url.py` | `test_create_login_url_falls_back_to_ssh_when_bootstrap_fails` |

**Changelog**：`docs/changelog/2026-07-08-btpanel-bootstrap-bt-installed-check.md`

---

### 2.2 宝塔一键登录：基础能力（main 历史，release 亦有部分重叠）

| 功能 | 文件 |
|------|------|
| 未配置时自动 bootstrap + 倒计时 | `useBtPanelLogin.ts`、`btpanel_service.py`（2026-06-21） |
| 临时 token 24h | `BT_TEMP_LOGIN_TTL_SECONDS`、`btpanel_service._login_url_via_api` |
| 登录 URL 短窗口 Redis 缓存 + 去重 | `login_url_lock.py`、`create_login_url` 双检锁 |
| 主列表/终端一键登录按钮 | `ServersPage.vue`、`TerminalPage.vue`、`ServerTableRowActions.vue` |
| 批量获取 API | `useBtPanelBatchBootstrap.ts` |
| API 端口漂移 SSH 修复 | `_try_login_url_via_api`、`_repair_ip_whitelist` |

---

### 2.3 Agent 监测与告警

| 功能 | 文件 | Changelog |
|------|------|-----------|
| 告警连续超阈门控（默认 3 次才 Telegram） | `server/utils/alert_streak.py`、`alert_metrics.py`、`watch_alerts.py` | `2026-07-04-alert-streak-gate.md` |
| Agent CPU 双模式采样 | `web/agent/cpu_metrics.py`、`server/api/agent.py` | `2026-07-02-agent-cpu-sampling.md` |
| 监测槽双模式 / Pin | `watch_service.py`、`useWatchPins.ts` | `2026-07-01-agent-watch-dual-mode.md` |
| 离线巡检发报前 SSH 复检心跳 | `offline_daily_report_schedule.py` | `d50120d1` |
| 统计卡：未设路径 / 离线 | `useServerStatsCards.ts` | `2026-07-02-stats-unset-path-offline-card.md` |

---

### 2.4 服务器列表与批量

| 功能 | 文件 |
|------|------|
| 分类筛选栏 / 备注弹窗 / 站点链接 | `ServerCategoryFilterBar.vue`、`ServerRemarkDialog.vue`、`serverSiteUrl.ts` |
| 未设路径表与主表对齐 | `ServerUnsetPathPanel.vue` |
| 检测路径：搜 `crmeb` 目录 | `server_batch_common.py` | `2026-07-05-detect-path-crmeb.md` |
| IP/域名定时检测 | `ip_domain_detect_schedule.py`、`ip_domain_detect_loop.py` | `2026-06-24-ip-domain-detect-schedule.md` |
| nginx 域名探测 | `nginx_domain_detect.py`、`site_host.py` |
| 跨服务器文件传输增强 | `server_file_transfer_service.py`、`useServerFileTransfer.ts` |
| 上传目录权限探测 | `files_upload_permissions.py` |

---

### 2.5 后台清理与配置

| 功能 | 文件 |
|------|------|
| 告警日志 / 审计日志定期清理 | `alert_log_purge.py`、`audit_log_purge.py`、`alert_log_repo.py` |
| 订阅 IP 刷新主 IP 修复 | `ip_allowlist_refresh.py` | `2026-06-23-subscription-ip-refresh-primary-fix.md` |

---

### 2.6 部署与发布源

| 功能 | 文件 |
|------|------|
| 默认 Gitea：`axs.kuma1xn.vip`（HTTPS） | `deploy/nexus-1panel.sh`、`nexus-1panel.secrets.sh.example` |
| 全量分批推送（避 Cloudflare 524） | `scripts/git-push-axs-full.sh` |
| 本机 rsync 生产部署 | `deploy/rsync-local-to-server.sh`、`deploy-production.sh` |

---

## 3. `release/20260708-axs` 独有、合并时必须带入 `main` 的功能

> 详见 release 内 `docs/release/20260708/PR-MERGE-说明-20260709.md`

### 3.1 宝塔 Session 1～2 小时掉线修复（核心）

**现象**：多窗口一键登录宝塔，约 1～2h 刷新后陆续掉线。

**根因**：部分宝塔 `task.py` 硬编码 `3600` 秒清理 `tmp_login` session，与 Nexus 24h tmp_token 不一致。

**行为**：

- SSH bootstrap / 一键登录前检测并 patch `task.py` → 读 `public.get_session_timeout()`，默认 `86400`
- 远端 `flock` + `mktemp` + atomic replace
- `extra_attrs.bt_panel` 记录 `session_cleanup_ttl_ok`、`session_cleanup_task_state` 等
- 登录 API 响应带 `diagnostics`（TTL 修补状态）
- `bootstrap_lock` 带 `wait_timeout_seconds`，避免并发 bootstrap 互踢

**关键文件**：

```text
server/application/services/btpanel_service.py   # _ensure_session_cleanup_ttl_for_login 等
server/infrastructure/btpanel/ssh_bootstrap.py   # ensure_session_cleanup_ttl() 远端脚本
server/infrastructure/btpanel/bootstrap_lock.py
server/api/btpanel.py                            # diagnostics 字段
tests/test_btpanel_temp_login_ttl.py
tests/test_btpanel_bootstrap_lock.py
tests/test_btpanel_get_config.py
```

---

### 3.2 `/app-v2` 第二后台

| 项 | 说明 |
|----|------|
| 路径 | `/app-v2/`（旧 `/app/` 保留） |
| 技术栈 | React + TS + Vite + shadcn/ui + TanStack Query/Table + Zustand |
| 目录 | `frontend-v2/`、`web/app-v2/` |
| 构建 | `Dockerfile.prod` 多阶段、`frontend-v2/scripts/scan-app-v2-sensitive.mjs` |
| 路由 | `server/main.py` 挂载静态 |

---

### 3.3 发布制品化工具链

```text
scripts/prepare_release_artifact.py
scripts/generate_release_bundle.py
scripts/scan_release_bundle.py
scripts/write_release_metadata.py
scripts/publish_release_bundle.py
scripts/run_local_release_gate.py
deploy/preflight-release-host.sh
deploy/apply-release-bundle.sh
```

发布包 SHA256（release 记录）：`46299832fb78e8cc196f85cf1928f34eea4deee82dbc83b67883394f0359036b`

---

### 3.4 文档与 Skill（release 独有目录）

```text
docs/release/20260708/          # 宝塔 Session、app-v2、安全巡检、发布记录
.skills/nexus-btpanel-review/
.skills/nexus-security-review/
.skills/nexus-ssh-safety/
```

---

## 4. 合并冲突热点（必须手工合）

### 4.1 `server/application/services/btpanel_service.py`

**两边都要保留**：

| 来源 | 保留内容 |
|------|----------|
| **main** | `BOOTSTRAP_LOGIN_HARD_FAIL_ERRORS`；bootstrap 失败 → SSH 回退（非凭据类不 raise） |
| **release** | `_ensure_session_cleanup_ttl_for_login`；`_session_cleanup_ttl_*`；`diagnostics`；`BootstrapLockTimeout` |

合并后 `_create_login_url_fresh` 推荐顺序：

1. 未配置 → immediate bootstrap（失败按 main 规则决定是否继续）
2. 已配置 → `_ensure_session_cleanup_ttl_for_login`
3. API 临时登录 → SSH 回退

### 4.2 `server/infrastructure/btpanel/ssh_bootstrap.py`

| 来源 | 保留 |
|------|------|
| **main** | `common.py` 真安装检测；`makedirs` config |
| **release** | `ensure_session_cleanup_ttl()`；`atomic_write_json`；`flock`；`session_cleanup_*` 字段 |

### 4.3 `server/main.py` / `Dockerfile.prod`

- 从 **release** 带入 `/app-v2` 静态挂载与构建阶段
- 保留 **main** 现有中间件与安装向导逻辑

### 4.4 `tests/test_btpanel_login_url.py`

- 合并 release 的 session TTL / lock 测试
- 保留 main 的 `test_create_login_url_falls_back_to_ssh_when_bootstrap_fails`

---

## 5. 合并后验证清单

```bash
# 单元测试（合并冲突解决后）
.venv/bin/pytest tests/test_btpanel_login_url.py tests/test_btpanel_ssh_bootstrap.py \
  tests/test_btpanel_temp_login_ttl.py tests/test_btpanel_bootstrap_lock.py -q

# 发布门禁（若合并了 release 脚本）
bash scripts/run_local_release_gate.sh
```

**人工验收**：

- [ ] `/app/` 旧后台 200
- [ ] `/app-v2/` 新后台 200（若合并 app-v2）
- [ ] 新机一键登录：bootstrap 失败仍能 SSH 打开（main 修复）
- [ ] 已装宝塔一键登录后 **2h 刷新仍在线**（release Session 修复）
- [ ] 同一子机连点一键登录不互踢 token（login_url_lock）
- [ ] `GET /api/btpanel/servers/{id}/login-url` 含 `diagnostics`（release）

---

## 6. 合并后部署

```bash
# 生产（中心机）
cd /opt/nexus
git remote set-url origin https://axs.kuma1xn.vip/admin/Nexus.git
git fetch origin main && git checkout main && git reset --hard origin/main
sudo env NEXUS_ROOT=/opt/nexus bash deploy/nexus-1panel.sh upgrade --skip-git

# 或 release 包路径
bash deploy/preflight-release-host.sh
bash deploy/apply-release-bundle.sh
```

---

## 7. Gitea PR 摘要（可直接粘贴）

```markdown
## 合并摘要

将 `release/20260708-axs` 合并入 `main`，统一 SSOT。

### release 带入

- 宝塔 task.py hardcoded 3600 → session_timeout 自动修复（解决 1～2h 掉线）
- `/app-v2` 第二后台
- 发布制品化 / preflight / apply-release-bundle
- bootstrap_lock、login diagnostics

### main 保留

- 一键登录 bootstrap 失败 → SSH 临时登录回退（新机 API 未就绪）
- ssh_bootstrap 真安装检测（common.py）+ config makedirs
- 6～7 月运维功能：告警连续门控、crmeb 路径检测、文件传输、日志清理等
- axs Gitea 默认发布源 + 分批推送脚本

### 冲突重点

`btpanel_service.py`、`ssh_bootstrap.py` — 两套宝塔逻辑必须同时保留，见本文 §4。

### 验证

pytest 宝塔专项 + `/app` + `/app-v2` + 2h 刷新不掉线
```

---

## 8. 相关文档索引

| 文档 | 路径 |
|------|------|
| release 原 PR 说明 | `docs/release/20260708/PR-MERGE-说明-20260709.md`（在 release 分支） |
| 宝塔掉线方案 | `docs/release/20260708/Nexus-宝塔一键登录长期掉线修复方案与代码改进.md` |
| app-v2 说明 | `docs/release/20260708/Nexus-app-v2-双后台实施说明-20260707.md` |
| main bootstrap 回退 | `docs/changelog/2026-07-08-btpanel-bootstrap-bt-installed-check.md` |
| Gitea 发布说明 | `docs/release/20260708/README-Gitea发布说明-20260708.md` |