Python 后端概览（server-python）

路径：packages/server-python
入口：app/main.py
技术：FastAPI + SQLAlchemy 2.0 + JWT (python-jose) + bcrypt + APScheduler + openpyxl

与 Java 单体对齐

同一套 contracts/openapi/rbac-api.yaml 契约，前端通过 VITE_API_BASE_URL 切换后端。Java 模块对照见 server-java 概览。

启动

# 根目录
docker compose up -d

cd packages/server-python
cp .env.example .env
pip install -e .

pnpm --filter @xichen-full-stack/server-python dev
# 或
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

默认端口 8000。API 文档：http://localhost:8000/docs

工作目录

须在 packages/server-python 下启动，否则读不到 .env。Docker 通过 --env-file 注入，不依赖 cwd。

目录结构

app/
├── main.py                  # FastAPI 入口、lifespan、CORS、异常处理、/uploads 静态挂载
├── api/
│   ├── deps.py              # JWT 鉴权、require_permission、DB Session
│   ├── request_utils.py     # 客户端 IP 等
│   └── v1/
│       ├── router.py        # 聚合 /api/v1 子路由
│       ├── auth.py          # 认证 + health
│       ├── database.py      # POST /system/database/init
│       ├── system.py        # 用户/角色/菜单/权限
│       ├── platform.py      # 部门/岗位/字典/参数/公告/文件
│       └── monitor.py       # 操作/登录日志、定时任务
├── core/
│   ├── config.py            # pydantic-settings（.env）
│   ├── database.py          # Engine / SessionLocal
│   ├── security.py          # JWT + bcrypt
│   ├── permissions.py       # 用户 → 权限码收集
│   └── menu_client.py       # 菜单 client 过滤 (web/desktop/all)
├── middleware/
│   └── oper_log.py          # 变更类 API 操作日志
├── models/
│   ├── system.py            # RBAC + 平台 ORM
│   └── monitor.py           # 日志 + 定时任务 ORM
├── schemas/                 # Pydantic DTO（common/auth/system/platform/monitor）
├── resources/db/
│   ├── schema.sql           # init 建表（与 contracts 对齐）
│   └── drop.sql             # init 删表
└── services/
    ├── auth_service.py
    ├── system_service.py    # 用户/角色/菜单/权限 + DatabaseInit
    ├── platform_service.py  # 部门/岗位/字典/参数/公告/文件 + Excel
    ├── monitor_service.py
    ├── data_scope_service.py
    ├── database_init.py
    ├── seed.py
    ├── scheduler_service.py # APScheduler
    ├── demo_task.py
    └── oper_log.py          # @oper_log 装饰器

项目根：pyproject.toml、.env.example、Dockerfile、可选 alembic/。

API 模块一览

路由文件	前缀	文档
auth.py	/api/v1	Auth 与菜单
database.py	/api/v1/system/database	System RBAC
system.py	/api/v1/system	System RBAC
platform.py	/api/v1/system	Platform 平台管理
monitor.py	/api/v1/monitor	Monitor 监控

另：main.py 挂载静态目录 /uploads（文件下载访问）。

配置

见 配置与环境。app/core/config.py 从 .env 读取。

数据库初始化

POST /api/v1/system/database/init — 读 app/resources/db/drop.sql + schema.sql，再 seed_data()，并重载 APScheduler。详见 数据库初始化。

lifespan 启动行为

main.py 的 lifespan：

1. 创建 UPLOAD_PATH 目录
2. 尝试 seed_data() — 已有用户则跳过；缺表失败仅 WARNING，不阻断启动
3. job_scheduler.init_from_db() — 加载启用中的定时任务
4. 关闭时 job_scheduler.shutdown()

生产环境应显式调用 init，勿仅依赖启动补种。

默认账号

init 或空库 seed 后：admin / admin123。

相关文档

• 权限依赖
• 配置与环境
• Docker 部署
• Java 概览