nginxserver/IMPLEMENTATION_PLAN.md

Nginx域名转发管理平台 - 实现方案文档

版本: 1.0 | 日期: 2026-06-09 | 状态: 已完成部署

---

一、项目概述

开发一个可视化管理平台，实现对 Nginx 反向代理规则的增删改查及 HTTPS 证书管理功能。

核心流程

用户 -> Vue.js前端(:3002) -> Spring Boot(:4002) -> Python API(10.1.1.160:5000) -> Nginx
                                                       |
                                                       v
                                                  MySQL(10.1.1.122:3306)

---

二、技术架构

层级	技术	版本	端口	部署位置
前端	Vue.js 3 + Element Plus	Vite 8	3002	独立部署
后端	Spring Boot + Maven	3.2.0 + JDK 17	4002	独立部署
数据库	MySQL	8.0.29	3306	10.1.1.122
Nginx API	Python Flask + Gunicorn	Flask 2.0.3	5000	10.1.1.160
代理服务器	Nginx	1.14.1	80/443	10.1.1.160

关键设计决策

1. 三层架构 - 前端不直接调用 Python API，通过 Spring Boot 中间层统一管理
2. 数据双写 - Python API 操作 Nginx 配置，Spring Boot 同步写入 MySQL 作为持久化
3. 内部 CA - 内网域名无法使用 Let's Encrypt，采用自建 CA 自动签发证书
4. 前后端直连 - 前端通过环境变量配置后端地址，不使用 Vite 代理

---

三、服务端点总览

3.1 Python API - 10.1.1.160:5000

方法	路径	功能
GET	/api/nginx/health	健康检查
GET	/api/nginx/rules	获取所有转发规则
GET	/api/nginx/rules/	获取单个规则
POST	/api/nginx/rules	新增转发规则
PUT	/api/nginx/rules/	修改转发规则
DELETE	/api/nginx/rules/	删除转发规则
POST	/api/nginx/reload	重载 Nginx 配置

3.2 Spring Boot - 端口 4002

方法	路径	功能
GET	/api/rules	获取规则列表（MySQL）
POST	/api/rules	新增规则（调Python -> 存MySQL -> 重载）
PUT	/api/rules/{id}	修改规则
DELETE	/api/rules/{id}	删除规则
POST	/api/rules/reload	手动重载 Nginx
GET	/api/rules/status	Nginx 运行状态

3.3 Vue.js 前端 - 端口 3002

• 布局: 左侧深色菜单栏 + 顶部标题栏 + 内容区
• 菜单: Nginx转发管理
• 功能: 规则列表展示、新增/修改/删除弹窗、HTTPS 自动提示
• 环境切换: .env.development / .env.production 配置不同后端地址

---

四、Nginx 转发规则逻辑

HTTP 规则

用户访问 http://test1.mokee.com
    -> Nginx 80端口匹配 server_name test1.mokee.com
    -> proxy_pass 转发到目标地址（如 http://10.1.1.11:8080）
    -> 透传 Host/X-Real-IP/X-Forwarded-For 头

HTTPS 规则

用户访问 https://test1.mokee.com
    -> Nginx 80端口返回 301 跳转到 https://
    -> Nginx 443端口匹配 server_name，使用 SSL 证书
    -> proxy_pass 转发到目标地址

生成的 Nginx 配置

HTTP 转发

server {
    listen 80;
    server_name test1.mokee.com;
    location / {
        proxy_pass http://10.1.1.11:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

HTTPS 转发

# HTTP 自动跳转 HTTPS
server {
    listen 80;
    server_name test1.mokee.com;
    return 301 https://$host$request_uri;
}

# HTTPS 转发
server {
    listen 443 ssl;
    server_name test1.mokee.com;

    ssl_certificate     /etc/nginx/ssl/test1.mokee.com.pem;
    ssl_certificate_key /etc/nginx/ssl/test1.mokee.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://10.1.1.11:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

---

五、HTTPS 证书方案

5.1 内部自建 CA

• 首次启动 Python API 时自动生成根 CA
• CA 证书: /etc/nginx/ssl/ca/ca.crt（有效期 10 年）
• CA 私钥: /etc/nginx/ssl/ca/ca.key（权限 600）
• 不占用 80/443/5000 端口

5.2 自动签发流程

选择 HTTPS -> SSLService.ensure_certificate(domain)
    -> 检查 /etc/nginx/ssl/<domain>.pem 是否存在且未过期
    -> 有效 -> 复用
    -> 无效/不存在 -> 使用内部 CA 签发新证书（有效期365天）

5.3 客户端信任

内网用户浏览器需导入 ca.crt 为受信任的根证书颁发机构:

# 下载 CA 证书
scp root@10.1.1.160:/etc/nginx/ssl/ca/ca.crt .

---

六、数据库设计

forwarding_rules 表

字段	类型	说明
id	BIGINT PK	主键
domain	VARCHAR(255) UNIQUE	域名
protocol	VARCHAR(10)	http/https
target	VARCHAR(500)	转发目标
config_file	VARCHAR(500)	Nginx配置文件路径
ssl_cert	VARCHAR(500)	SSL证书路径
ssl_key	VARCHAR(500)	SSL私钥路径
status	TINYINT	0-已删除 1-正常
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

certificates 表

字段	类型	说明
id	BIGINT PK	主键
domain	VARCHAR(255) UNIQUE	域名
cert_path	VARCHAR(500)	证书文件路径
key_path	VARCHAR(500)	私钥文件路径
issue_date	DATETIME	签发日期
expire_date	DATETIME	过期日期
status	VARCHAR(20)	active/expired/revoked
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

---

七、项目文件结构

nginxServer/
├── nginx-python-api/                # Python Flask API 源码
│   ├── app.py                       # 主入口（7个API端点）
│   ├── services/
│   │   ├── nginx_service.py         # Nginx配置CRUD + reload
│   │   └── ssl_service.py           # 内部CA + 证书签发
│   ├── requirements.txt             # flask + gunicorn
│   ├── gunicorn_config.py           # 生产环境配置
│   └── deploy.sh                    # 一键部署脚本
│
├── nginx-manager-backend/           # Spring Boot 源码
│   ├── pom.xml
│   └── src/main/java/com/mokee/nginx/
│       ├── NginxManagerApplication.java
│       ├── controller/
│       │   ├── ForwardingRuleController.java
│       │   └── GlobalExceptionHandler.java
│       ├── service/
│       │   ├── ForwardingRuleService.java
│       │   └── PythonApiClient.java
│       ├── entity/ForwardingRule.java
│       ├── repository/ForwardingRuleRepository.java
│       ├── dto/RuleRequest.java
│       ├── dto/ApiResponse.java
│       └── config/RestTemplateConfig.java
│
├── nginx-manager-frontend/          # Vue.js 3 前端
│   ├── .env.development             # 开发环境变量
│   ├── .env.production              # 生产环境变量
│   ├── vite.config.js               # Vite配置（端口3002）
│   └── src/
│       ├── App.vue                  # 根组件
│       ├── layout/MainLayout.vue    # 左侧菜单布局
│       ├── views/NginxForwarding.vue # 转发管理页面
│       ├── api/nginxApi.js          # API请求封装
│       └── router/index.js          # 路由配置
│
├── sql/init.sql                     # MySQL建库建表脚本
├── IMPLEMENTATION_PLAN.md           # 本文档 - 实现方案
└── DEPLOYMENT.md                    # 部署文档 - 含全部命令

---

八、启动命令

# === 10.1.1.160 服务器（已配置开机自启）===
systemctl start nginx-api     # Python API (5000)
systemctl start nginx         # Nginx (80/443)

# === Spring Boot 后端 ===
cd nginx-manager-backend
mvn spring-boot:run          # 开发模式（端口4002）

# === Vue.js 前端 ===
cd nginx-manager-frontend
npm run dev                  # 开发模式（端口3002，读.env.development）
npm run build                # 生产构建（读.env.production）