WonderQ-Project/WonderQ-Admin

WonderQ-Admin

独立的 WonderQ 后端 API 服务，基于 Python、FastAPI、SQLAlchemy 2、Alembic、PostgreSQL、JWT 和 Pydantic。

本地手动启动

以下命令默认在项目根目录执行：D:\www\znkj\WonderQ-Admin。

1. 准备环境变量

首次启动先复制环境变量模板：

Copy-Item .env.example .env

然后编辑 .env，至少确认以下配置：

• DATABASE_URL：本地 Docker PostgreSQL 默认使用 localhost:5433。
• JWT_SECRET：生产环境必须替换为高强度随机值。
• REDIS_URL：管理员会话、Refresh Token 和权限缓存使用的 Redis 地址。
• ADMIN_PERMISSION_CACHE_SECONDS：管理员权限菜单缓存秒数，默认 300。
• ADMIN_LOGIN_RATE_LIMIT / ADMIN_LOGIN_RATE_WINDOW_SECONDS：登录限流窗口，默认每个 IP+账号 60 秒最多 5 次。
• ADMIN_ACCESS_EXPIRES_MINUTES、ADMIN_REFRESH_EXPIRES_DAYS：管理员访问令牌和刷新令牌有效期。
• OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS_ENDPOINT、OSS_BUCKET_NAME：填写实际 OSS 配置；真实密钥只放在 .env 或部署平台密钥中，不提交到 Git。

菜单管理接口 GET/POST/PATCH/DELETE /api/admin/system/menus 维护目录、页面和按钮的父子树。服务端校验父级存在、禁止按钮作为父级、禁止循环归属和重复权限标识；具体字段规则以 docs/admin-api-requirements.md 为准。

2. 创建并启用 Python 虚拟环境

首次启动或 .venv 不存在时执行：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

如果 PowerShell 阻止执行激活脚本，可临时允许当前进程执行脚本后再激活：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

后续日常启动只需要重新激活虚拟环境：

.\.venv\Scripts\Activate.ps1

3. 启动依赖服务

启动本地 PostgreSQL 和 Redis：

docker-compose up -d postgres redis

确认容器状态：

docker-compose ps

4. 初始化或升级数据库

首次启动、迁移变更后执行：

python -m alembic upgrade head

空库首次导入初始化内容时执行：

python -m app.seed

注意：python -m app.seed 会初始化站点内容和媒体数据；已有业务数据时不要重复执行。只需要确保默认后台账号存在时，用：

python -m app.seed --no-reset

5. 启动 API 服务

开发模式启动：

python -m uvicorn app.main:app --host 0.0.0.0 --port 4000 --reload

如果需要手动重启 4001 端口服务，先释放端口，再重新运行：

$port = 4001
$listenerPids = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue |
  Select-Object -ExpandProperty OwningProcess -Unique
foreach ($listenerPid in $listenerPids) {
  Get-CimInstance Win32_Process |
    Where-Object { $_.ParentProcessId -eq $listenerPid } |
    ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
  Stop-Process -Id $listenerPid -Force -ErrorAction SilentlyContinue
}
python -m uvicorn app.main:app --host 0.0.0.0 --port 4001 --reload

启动后访问：

• 健康检查：http://localhost:4000/health
• OpenAPI 文档：http://localhost:4000/docs
• 默认后台账号：admin@example.com / ChangeMe123!

日常启动速查

从 D:\www\znkj\WonderQ-Project 根目录手动启动时，先确认 Docker Desktop 已运行，通常只需要：

Set-Location .\WonderQ-Admin
.\.venv\Scripts\Activate.ps1
docker-compose up -d postgres redis
python -m alembic upgrade head
python -m uvicorn app.main:app --host 0.0.0.0 --port 4001 --reload

Docker 部署

完整本地部署：

docker-compose up --build

服务包含：

• api：FastAPI 服务，默认监听 4000
• postgres：PostgreSQL 16，宿主机端口 5433
• redis：Redis 7，宿主机端口 6380

已有生产数据库迁移到 Python 版时，先备份数据库，再执行：

alembic stamp head

空库或全新环境使用：

python -m alembic upgrade head
python -m app.seed

目录说明

• app/：FastAPI 应用、路由、鉴权、数据库模型、schema、seed 逻辑。
• app/routers/public.py：H5 Public API。
• app/routers/admin.py：后台 Admin API。
• app/models.py：SQLAlchemy ORM，兼容原 Prisma 表结构。
• alembic/：数据库迁移 baseline。
• data/：初始化数据文件目录；当前站点内容由 app/content.py 和 app/seed.py 管理。
• docker-compose.yml：API、PostgreSQL 和 Redis 编排。
• tests/：基础单元和接口冒烟测试。

常用命令

命令	说明
python -m uvicorn app.main:app --reload --port 4000	启动开发服务
python -m alembic upgrade head	创建或升级数据库结构
alembic stamp head	标记已有数据库已处于当前 baseline
python -m app.seed	导入初始化内容
python -m app.seed --no-reset	只确保默认后台账号存在
python -m pytest	运行测试
docker-compose up --build	构建并启动完整服务

API 兼容范围

Python 版保留原有核心路径：

• GET /health
• GET /api/public/site-config
• POST /api/public/auth/phone-login
• GET /api/public/auth/me
• POST /api/public/leads
• POST /api/admin/auth/login
• POST /api/admin/auth/refresh、POST /api/admin/auth/logout
• GET /api/admin/system/profile
• /api/admin/system/users、/api/admin/system/roles、/api/admin/system/menus、/api/admin/system/depts
• GET /api/admin/me
• GET /api/admin/dashboard
• GET /api/admin/site-config
• PATCH /api/admin/site-config/{module}/{id}
• GET /api/admin/leads
• PATCH /api/admin/leads/{id}/status
• GET /api/admin/media-assets
• POST /api/admin/media-assets/upload

注意事项

• 生产环境必须替换 JWT_SECRET，禁止使用示例值。
• 真实环境变量只放在 .env 或部署平台密钥中，不提交到 Git。
• python -m app.seed 会初始化开发站点内容和媒体数据；不要直接对生产库执行。
• 保留现有 PostgreSQL 数据时使用 alembic stamp head，不要在已有生产表上直接运行初始建表迁移。