优化更新

2026-09-13 20:29:19 +08:00
parent d7a081e8b7
commit 74f41f651f
65 changed files with 1061 additions and 1321 deletions
@@ -15,11 +15,7 @@
 首次部署时，使用初始化脚本一键完成建库、建表、Flask-Migrate stamp：

 ```bash
-# 方式一：直接运行脚本
 python scripts/setup_db.py
-
-# 方式二：Make 命令
-make db-init
 ```

 :::tip 初始化流程
@@ -40,7 +36,7 @@ make db-init
 flask db migrate -m "描述变更内容"

 # 或使用 Make 命令
-make migrate-revision
+flask db migrate
 ```

 :::tip 注意事项
@@ -56,7 +52,7 @@ make migrate-revision
 flask db upgrade

 # 或使用 Make 命令
-make migrate-upgrade
+flask db upgrade
 ```

 ### 回滚迁移
@@ -87,7 +83,7 @@ flask db history
 flask db stamp head

 # 或使用 Make 命令
-make migrate-stamp
+flask db stamp head
 ```

 ## 跨库数据迁移
@@ -111,7 +107,7 @@ make migrate-stamp

 | 目标库 | 驱动包 | 说明 |
 |:----|:----|:----|
-| PostgreSQL | psycopg[binary] | psycopg3 |
+| PostgreSQL | psycopg2-binary | psycopg2 |
 | SQL Server | pymssql | - |
 | SQLite | 内置 | 无需额外驱动 |
 | Oracle | oracledb | thin 模式，无需安装 Oracle Client |
@@ -362,14 +358,14 @@ CREATE SEQUENCE flask_user_id_seq START WITH <max_id+1>;

 | 场景 | 命令 |
 |------|------|
-| 全新安装 | `make db-init` |
-| 模型变更后生成迁移 | `make migrate-revision` |
-| 应用迁移 | `make migrate-upgrade` |
+| 全新安装 | `python scripts/setup_db.py` |
+| 模型变更后生成迁移 | `flask db migrate` |
+| 应用迁移 | `flask db upgrade` |
 | 回滚一次迁移 | `flask db downgrade -1` |
-| 标记已有库为最新 | `make migrate-stamp` |
+| 标记已有库为最新 | `flask db stamp head` |
 | 跨库迁移干跑 | `make db-migrate-dry-run ARGS="..."` |
 | 跨库迁移执行 | `make db-migrate ARGS="..."` |

 ## 总结

-数据库迁移分为结构迁移（Flask-Migrate / Alembic）和数据迁移（`migrate_db.py`）两部分。全新安装用 `make db-init`，模型变更用 Flask-Migrate 自动生成迁移脚本，跨库切换用 `migrate_db.py` 数据泵。建议每次迁移前先干跑确认，生产环境务必做好备份。
+数据库迁移分为结构迁移（Flask-Migrate / Alembic）和数据迁移（`migrate_db.py`）两部分。全新安装用 `python scripts/setup_db.py`，模型变更用 Flask-Migrate 自动生成迁移脚本，跨库切换用 `migrate_db.py` 数据泵。建议每次迁移前先干跑确认，生产环境务必做好备份。
@@ -12,7 +12,7 @@

 ## Dockerfile 详解

-项目根目录 `Dockerfile` 完整内容：
+`docker/Dockerfile` 完整内容：

 ```dockerfile
 # 基础镜像：Python 3.11-slim
@@ -113,18 +113,18 @@ Docker 部署时，`docker-compose.yml` 通过 `env_file: .env` 注入环境变
 | DB_DRIVER | 数据库 | 依赖包 | 连接串格式 |
 |-----------|--------|--------|-----------|
 | mysql（默认） | MySQL 8.x | PyMySQL | `mysql+pymysql://user:pass@host:3306/db` |
-| postgresql | PostgreSQL 14+ | psycopg[binary] | `postgresql+psycopg://user:pass@host:5432/db` |
+| postgresql | PostgreSQL 14+ | psycopg2-binary | `postgresql+psycopg2://user:pass@host:5432/db` |
 | mssql | SQL Server 2019+ | pymssql | `mssql+pymssql://user:pass@host:1433/db` |
 | sqlite | SQLite 3 | 内置 | `sqlite:///path/to/db.sqlite3` |
 | oracle | Oracle 12c+ | oracledb | `oracle+oracledb://user:pass@host:1521/db` |

 :::tip 切换数据库后
-切换数据库驱动后，需要重新初始化数据库结构。项目 Makefile 提供常用命令：
+切换数据库驱动后，需要重新初始化数据库结构。常用命令：
 ```bash
-make db-init              # 初始化数据库（建库 + SQL 导入 + 补表 + flask db stamp）
-make migrate-revision     # 生成增量迁移脚本
-make migrate-upgrade      # 应用迁移
-make migrate-stamp        # 标记当前库已到基线
+python scripts/setup_db.py   # 初始化数据库（建库 + SQL 导入 + 补表 + flask db stamp）
+flask db migrate             # 生成增量迁移脚本
+flask db upgrade             # 应用迁移
+flask db stamp head        # 标记当前库已到基线
 make db-migrate ARGS="..."  # 跨库数据迁移
 ```
 :::
@@ -18,16 +18,14 @@
 Flask 应用提供健康检查路由，可用于负载均衡器或容器编排的探针配置：

 ```bash
-# 基础健康检查
-GET /api/v1/health
+# 基础健康检查（无需认证，已在登录白名单中）
+GET /health

 # 响应示例
 {
    "code": 0,
    "data": {
-        "status": "healthy",
-        "version": "1.0.0",
-        "uptime": 3600
+        "status": "ok"
    },
    "msg": "操作成功",
    "ok": true
@@ -38,7 +36,7 @@ GET /api/v1/health
 在 Dockerfile 中配置 HEALTHCHECK：
 ```dockerfile
 HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
-  CMD curl -f http://localhost:8021/api/v1/health || exit 1
+  CMD curl -f http://localhost:8021/health || exit 1
 ```
 :::

@@ -79,7 +77,7 @@ HEALTHCHECK --interval=30s --timeout=10s --retries=3 \

 ```
 2026-09-05 10:30:15 [INFO] src.app: Application startup complete
-2026-09-05 10:30:16 [WARNING] src.middleware.rate_limit: Rate limit exceeded for 192.168.1.100
+2026-09-05 10:30:16 [WARNING] src.middleware.auth: Login attempt locked for user admin from 192.168.1.100
 2026-09-05 10:30:17 [ERROR] src.modules.auth.service: Login failed for user admin
 ```

@@ -15,7 +15,7 @@ Nginx 作为反向代理服务器，承担静态资源服务、API 请求转发

 ## 基础配置

-项目提供了 Nginx 配置模板 `deploy/nginx.conf`，按需修改即可使用：
+以下为推荐的 Nginx 配置模板，按需修改后保存为 `/etc/nginx/conf.d/djangoadmin.conf`：

 ```nginx
 upstream flask_backend {
@@ -101,8 +101,7 @@ cd ui && pnpm build
 mkdir -p /data/apps/djangoadmin/frontend
 cp -r ui/dist /data/apps/djangoadmin/frontend/

-# 3. 拷贝 Nginx 配置
-cp deploy/nginx.conf /etc/nginx/conf.d/djangoadmin.conf
+# 3. 将上方配置保存为 /etc/nginx/conf.d/djangoadmin.conf

 # 4. 修改配置中的实际值（server_name、root 等）

@@ -12,7 +12,7 @@ Supervisor 是一个 Python 编写的进程管理工具，用于在 Linux 服务

 ## 配置文件示例

-项目提供了 Supervisor 配置模板 `deploy/supervisor.conf`，完整内容：
+以下为推荐的 Supervisor 配置模板，按需修改后保存到 `/etc/supervisor/conf.d/`：

 ```ini
 ; Supervisor 进程管理示例配置
@@ -47,7 +47,7 @@ environment=PYTHONUNBUFFERED=1
 # 1. 修改 command 中的虚拟环境路径
 # 2. 修改 directory 为项目实际路径
 # 3. 修改 stdout_logfile 为日志实际路径
-cp deploy/supervisor.conf /etc/supervisor/conf.d/djangoadmin-flask.conf
+# 将上方配置保存为 /etc/supervisor/conf.d/djangoadmin-flask.conf
 ```
 :::

@@ -192,4 +192,4 @@ startsecs=10

 ## 总结

-Supervisor 是 Linux 环境下管理 Flask 进程的可靠方案，提供自动重启、日志轮转、进程监控等能力。配置文件位于 `deploy/supervisor.conf`，修改路径后复制到 `/etc/supervisor/conf.d/` 即可使用。生产环境建议配合 systemd 管理 Supervisor 自身的启动。
+Supervisor 是 Linux 环境下管理 Flask 进程的可靠方案，提供自动重启、日志轮转、进程监控等能力。按上方模板创建配置文件，修改路径后复制到 `/etc/supervisor/conf.d/` 即可使用。生产环境建议配合 systemd 管理 Supervisor 自身的启动。
@@ -94,8 +94,6 @@ flask db history
 # 执行迁移
 flask db upgrade

-# 或使用 Make 命令
-make migrate-upgrade
 ```

 :::warning 迁移前确认
@@ -124,7 +122,7 @@ sudo systemctl restart djangoadmin-flask
 sudo supervisorctl status djangoadmin-flask

 # 2. 检查健康端点
-curl -s http://127.0.0.1:8021/api/v1/health | python -m json.tool
+curl -s http://127.0.0.1:8021/health | python -m json.tool

 # 3. 检查日志
 tail -f /data/apps/logs/supervisor.out.log