145 lines
7.3 KiB
Markdown
145 lines
7.3 KiB
Markdown
# 后端工程化结构说明
|
||
|
||
本文给后端维护人员阅读。它说明服务端为什么从单个 `main.py` 拆成 `routes / services / repositories / schemas`，以及后续继续工程化时应该把代码放在哪里。
|
||
|
||
## 目标
|
||
|
||
服务端后端不再继续把所有配置、鉴权、审计、页面入口和业务接口堆在 `main.py` 里，而是逐步改成成熟 FastAPI 后台项目常见的分层结构。
|
||
|
||
当前采用的成熟框架和模板生态：
|
||
|
||
- 后端 HTTP 框架：FastAPI。
|
||
- 运行服务：Uvicorn。
|
||
- 请求模型和参数校验：FastAPI 自带的 Pydantic 体系。
|
||
- 管理后台前端：GitHub 上的 pure-admin-thin / vue-pure-admin 生态，技术栈是 Vue3、Element Plus、TypeScript、Vite。
|
||
- 对象存储：MinIO。
|
||
|
||
后端工程化参考方向：
|
||
|
||
- FastAPI 官方 full-stack 模板：后端工程结构、配置、JWT、数据库模型、迁移、Docker。
|
||
- FastAPI Users：用户、认证、JWT、密码哈希、用户管理。
|
||
- 现有 SimCAE 业务：版本发布、Manifest 签名、License、设备、崩溃报告、日志审计。
|
||
|
||
当前说明：
|
||
|
||
- 目前不是把某个 GitHub 后端模板整套照搬进项目，而是采用 FastAPI 作为成熟后端框架，并按成熟 FastAPI 后台项目的常见结构做工程化拆分。
|
||
- 管理后台前端已经基于 pure-admin-thin 这类成熟后台模板改造。
|
||
- 管理员鉴权已经从单一 `ADMIN_TOKEN` 升级为用户名/密码登录、Argon2 密码哈希、JWT access/refresh token、RBAC 权限检查和管理员用户管理页面。管理后台接口不再保留旧的单令牌登录入口；`ADMIN_TOKEN` 仍作为服务端兜底令牌和崩溃报告管理兜底令牌保留。
|
||
|
||
## 当前已落地
|
||
|
||
已经新增模板化目录：
|
||
|
||
```text
|
||
app/
|
||
api/
|
||
router.py
|
||
routes/
|
||
admin_auth.py
|
||
admin_license.py
|
||
admin_policy.py
|
||
admin_version.py
|
||
admin_app_channel.py
|
||
admin_crash_report.py
|
||
admin_device.py
|
||
admin_logs.py
|
||
admin_config.py
|
||
admin_publish.py
|
||
client_update.py
|
||
crash_api.py
|
||
frontend.py
|
||
core/
|
||
config.py
|
||
security.py
|
||
audit.py
|
||
db/
|
||
repositories/
|
||
admin_user_repository.py
|
||
app_channel_repository.py
|
||
crash_report_repository.py
|
||
device_repository.py
|
||
license_repository.py
|
||
log_repository.py
|
||
policy_repository.py
|
||
version_repository.py
|
||
client_update_repository.py
|
||
publish_repository.py
|
||
schemas/
|
||
admin_auth.py
|
||
license.py
|
||
policy.py
|
||
version.py
|
||
app_channel.py
|
||
device.py
|
||
log.py
|
||
admin_config.py
|
||
client_update.py
|
||
services/
|
||
common_service.py
|
||
license_service.py
|
||
signing_service.py
|
||
admin_config_service.py
|
||
device_credential_service.py
|
||
publish_service.py
|
||
crash_api_service.py
|
||
```
|
||
|
||
当前已经从 `main.py` 抽出的通用能力：
|
||
|
||
- `app/core/config.py`：统一读取 `.env`、路径配置和基础 settings。
|
||
- `app/core/security.py`：管理员 JWT、Argon2 密码哈希、RBAC 权限检查、令牌摘要、`.env` 写入工具。
|
||
- `app/core/audit.py`：管理后台写操作审计中间件。
|
||
- `app/api/routes/frontend.py`：管理后台静态页面、favicon、platform-config、health 路由。
|
||
- `app/api/routes/admin_license.py`：License 创建、列表、禁用/启用、软删除接口。
|
||
- `app/api/routes/admin_policy.py`：渠道更新策略查询和保存接口。
|
||
- `app/api/routes/admin_version.py`：版本列表、设为最新、删除、客户端协议修改、离线包下载接口。
|
||
- `app/api/routes/admin_app_channel.py`：应用列表、应用创建、渠道列表、渠道保存接口。
|
||
- `app/api/routes/admin_logs.py`：升级日志、下载日志、管理员审计日志的列表、删除和清空接口。
|
||
- `app/api/routes/admin_crash_report.py`：崩溃报告管理列表和附件下载接口。
|
||
- `app/api/routes/admin_device.py`：设备列表和设备禁用/恢复接口。
|
||
- `app/api/routes/admin_auth.py`：用户名密码登录、JWT 刷新、登录检查、修改密码、管理员用户列表、创建、角色编辑、禁用/启用和重置密码接口。
|
||
- `app/api/routes/admin_config.py`：运行时配置、客户端配置生成接口，以及服务端兜底令牌变更接口。
|
||
- `app/api/routes/admin_publish.py`：管理端发布新版本接口，包含发布锁和管理员鉴权。
|
||
- `app/api/routes/client_update.py`：客户端设备登记、更新检测、下载链接、Manifest、下载日志和升级结果上报接口。
|
||
- `app/api/routes/crash_api.py`：崩溃报告健康检查、报告上传/下载和符号包上传接口。
|
||
- `app/schemas/`：License、策略、版本管理接口的 Pydantic 请求模型。
|
||
- `app/services/common_service.py`：渠道校验、版本号比较、策略行转换等通用业务函数。
|
||
- `app/services/license_service.py`：License Key 加密保存和解密展示。
|
||
- `app/services/signing_service.py`：Manifest、策略、设备身份签名。
|
||
- `app/services/admin_config_service.py`：管理端运行时配置和客户端配置默认值生成。
|
||
- `app/services/device_credential_service.py`：客户端设备凭证验签、有效性校验和 last_seen 更新。
|
||
- `app/services/publish_service.py`：发布包表单解析、Release 目录校验、压缩包解压、空间检查和 MinIO 上传。
|
||
- `app/services/crash_api_service.py`：崩溃报告接口鉴权、multipart 校验、文件落盘、幂等校验和符号包处理。
|
||
- `app/repositories/`：管理后台已迁移接口的数据库读写层，route 不再直接拼 SQL 或打开数据库连接。
|
||
- `app/api/router.py`：统一注册基础路由。
|
||
- `main.py`：已经压缩为服务入口，只保留生命周期、MinIO 初始化、静态挂载和全局客户端鉴权。
|
||
|
||
当前业务接口路径保持不变，避免影响 Launcher、Updater 和已部署管理页面。
|
||
|
||
## 后续迁移路线
|
||
|
||
后续不建议一次性重写全部后端，而是按下面顺序迁移：
|
||
|
||
1. 继续接入更完整的成熟用户认证模块，例如 FastAPI Users，替换当前轻量用户表。
|
||
2. 将现有权限点继续细化，例如 `version:publish`、`license:create`、`audit:read`。
|
||
3. 管理后台常用业务接口、客户端更新接口、版本发布接口、崩溃报告接口已经按领域拆到 `app/api/routes/`，并将 SQL 下沉到 `app/repositories/`。
|
||
4. 继续将请求/响应 `dict` 改成 `app/schemas/` 下的 Pydantic 模型。
|
||
5. 继续补齐请求/响应模型、权限模型、异常模型，让接口契约更清晰。
|
||
6. 继续细化 repository，后续可把 SQLite SQL 逐步迁到 ORM 或统一查询层。
|
||
7. 引入 ORM 和迁移工具，例如 SQLModel/SQLAlchemy + Alembic。
|
||
8. 增加登录失败审计、登录限流、会话管理和更细粒度 Token 轮换。
|
||
9. 保持客户端接口 `/api/v1/...` 尽量兼容，避免客户端 SDK 重编。
|
||
|
||
## 为什么不是直接删除 main.py
|
||
|
||
`main.py` 原来包含大量已经跑通的业务逻辑：
|
||
|
||
- 版本发布和压缩包解包。
|
||
- Manifest 哈希和签名。
|
||
- MinIO 文件上传、下载授权。
|
||
- 设备身份签发和校验。
|
||
- License 管理。
|
||
- 崩溃报告上传、查询和下载。
|
||
|
||
这些是 SimCAE 自有业务，GitHub 模板不会直接提供。当前已经完成第一轮“搬家式重构”：业务模块进入 `routes/services/repositories`，入口文件不再堆业务代码。后续可以继续做更深的工程化，例如 ORM、JWT 用户体系、角色权限和 Alembic 数据库迁移。
|