4c245f0d1f
新增服务端菜单校验与归一化逻辑，完善菜单相关Schema；前端实现条件渲染的菜单编辑器，支持搜索式图标选择器与父级树过滤。新增媒体URL统一处理工具修复管理端本地静态资源路径映射问题，更新全部相关文档、技术决策记录与测试用例。本次变更不影响WonderQ-MiniAPP端。
205 lines
6.7 KiB
Markdown
205 lines
6.7 KiB
Markdown
# WonderQ-Admin
|
||
|
||
独立的 WonderQ 后端 API 服务，基于 Python、FastAPI、SQLAlchemy 2、Alembic、PostgreSQL、JWT 和 Pydantic。
|
||
|
||
## 本地手动启动
|
||
|
||
以下命令默认在项目根目录执行：`D:\www\znkj\WonderQ-Admin`。
|
||
|
||
### 1. 准备环境变量
|
||
|
||
首次启动先复制环境变量模板：
|
||
|
||
```powershell
|
||
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`](../docs/admin-api-requirements.md) 为准。
|
||
|
||
### 2. 创建并启用 Python 虚拟环境
|
||
|
||
首次启动或 `.venv` 不存在时执行：
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
.\.venv\Scripts\Activate.ps1
|
||
python -m pip install -r requirements.txt
|
||
```
|
||
|
||
如果 PowerShell 阻止执行激活脚本，可临时允许当前进程执行脚本后再激活：
|
||
|
||
```powershell
|
||
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
||
.\.venv\Scripts\Activate.ps1
|
||
```
|
||
|
||
后续日常启动只需要重新激活虚拟环境：
|
||
|
||
```powershell
|
||
.\.venv\Scripts\Activate.ps1
|
||
```
|
||
|
||
### 3. 启动依赖服务
|
||
|
||
启动本地 PostgreSQL 和 Redis：
|
||
|
||
```powershell
|
||
docker-compose up -d postgres redis
|
||
```
|
||
|
||
确认容器状态：
|
||
|
||
```powershell
|
||
docker-compose ps
|
||
```
|
||
|
||
### 4. 初始化或升级数据库
|
||
|
||
首次启动、迁移变更后执行：
|
||
|
||
```powershell
|
||
python -m alembic upgrade head
|
||
```
|
||
|
||
空库首次导入初始化内容时执行：
|
||
|
||
```powershell
|
||
python -m app.seed
|
||
```
|
||
|
||
注意：`python -m app.seed` 会初始化站点内容和媒体数据；已有业务数据时不要重复执行。只需要确保默认后台账号存在时，用：
|
||
|
||
```powershell
|
||
python -m app.seed --no-reset
|
||
```
|
||
|
||
### 5. 启动 API 服务
|
||
|
||
开发模式启动：
|
||
|
||
```powershell
|
||
python -m uvicorn app.main:app --host 0.0.0.0 --port 4000 --reload
|
||
```
|
||
|
||
如果需要手动重启 4001 端口服务，先释放端口，再重新运行：
|
||
|
||
```powershell
|
||
$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 已运行，通常只需要：
|
||
|
||
```powershell
|
||
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 部署
|
||
|
||
完整本地部署：
|
||
|
||
```bash
|
||
docker-compose up --build
|
||
```
|
||
|
||
服务包含：
|
||
|
||
- `api`：FastAPI 服务，默认监听 `4000`
|
||
- `postgres`：PostgreSQL 16，宿主机端口 `5433`
|
||
- `redis`：Redis 7，宿主机端口 `6380`
|
||
|
||
已有生产数据库迁移到 Python 版时，先备份数据库，再执行：
|
||
|
||
```bash
|
||
alembic stamp head
|
||
```
|
||
|
||
空库或全新环境使用：
|
||
|
||
```bash
|
||
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`，不要在已有生产表上直接运行初始建表迁移。
|