# 架构优化 — 配置分发与部署设计报告

> 更新: 2026-05-22 — 反映 PHP→API 迁移进度

## 一、优化目标

1. **配置源统一** — MySQL settings 表为唯一动态配置源，.env 仅启动必需
2. **主服务器 IP 变更自动化** — Agent config.json 推送 + 热重载
3. **全量可配置化** — 无硬编码路径/域名/IP，环境变量驱动部署

## 二、配置架构

```
【当前架构 — 已实现】

install.php (部署阶段)
  → 写入 config.php (PHP 前端)
  → 写入 .env (NEXUS_ 前缀, Python 启动必需)
  → 写入 MySQL settings 表 (动态配置)

Python 启动
  → 读 .env (SECRET_KEY, DATABASE_URL, API_KEY — 不可改)
  → load_settings_from_db() → MySQL settings 覆盖可改项

前端运行
  → api.js → JWT 认证 → FastAPI API
  → 不再依赖 PHP Session

配置变更
  → settings.html → POST /api/settings → MySQL
  → Python 重启后 load_settings_from_db() 自动生效
```

## 三、已实现改动

### 3.1 配置统一

| 组件 | 实现 |
|------|------|
| `server/config.py` | `load_settings_from_db()` — 启动时从 MySQL settings 表读取 |
| `server/api/settings.py` | `GET/POST /api/settings` — 前端读写配置 |
| MySQL settings 表 | key-value 存储: api_key, telegram, thresholds, pool_size |
| `.env` | NEXUS_ 前缀，启动必需项 (SECRET_KEY, DATABASE_URL) |

**不可改配置** (`.env` only):
- SECRET_KEY, API_KEY, ENCRYPTION_KEY, DATABASE_URL

**可改配置** (MySQL 可覆盖):
- system_name/title, pool_size/overflow, redis_url, 告警阈值, Telegram

### 3.2 配置分发到子服务器

| 组件 | 实现 |
|------|------|
| `web/agent/config.example.json` | 统一 JSON 格式，替代 YAML |
| `web/agent/install.sh` | Agent 安装脚本 |

### 3.3 全量可配置化

| 组件 | 实现 |
|------|------|
| `NEXUS_DEPLOY_PATH` | 部署路径，所有脚本读取此变量 |
| `NEXUS_CORS_ORIGINS` | CORS 域名，逗号分隔 |
| `deploy/nexus.conf` | 模板化 Supervisor 配置 ({{DEPLOY_DIR}}) |
| `deploy/nginx_*.conf` | 模板化 Nginx 配置 ({{SERVER_NAME}}) |
| `deploy/health_monitor.sh` | 从 .env 读取 NEXUS_DEPLOY_DIR |

## 四、待实现建议

### 4.1 推送前预览 (rsync dry-run)

**设计**: 推送对话框点「预览」→ `rsync -avzn --stats` dry-run → 显示预计传输文件数和大小

### 4.2 settings 页 tab 化

**设计**: 当前所有设置堆在一个长页面

```
[TOTP] [修改密码] [密码预设] [导入导出] [系统配置] [推送配置]
```

### 4.3 Agent 自动化安装增强

**设计**: install.sh 配合 config.json：
- 读取 config.example.json → 提示用户填入 central.url → 生成 config.json
- 不再依赖环境变量

### 4.4 install.php → install.html 迁移

**设计**: install.php 是最后残留的 PHP 页面，迁移到纯静态 HTML + FastAPI API 后可移除 PHP-FPM 依赖
