111 lines
2.5 KiB
Markdown
111 lines
2.5 KiB
Markdown
|
# 基础鉴权说明
|
|||
|
|
|
|||
|
|
本文档说明当前 Python 重构项目里已经落地的第一版鉴权基座。
|
|||
|
|
|
|||
|
|
这一轮只解决：
|
|||
|
|
|
|||
|
|
- 登录页
|
|||
|
|
- 登录 / 登出流程
|
|||
|
|
- server-side session
|
|||
|
|
- 一个最小受保护页面
|
|||
|
|
|
|||
|
|
这一轮明确不解决：
|
|||
|
|
|
|||
|
|
- 完整 config persistence
|
|||
|
|
- 完整 config CRUD
|
|||
|
|
- 多用户权限系统
|
|||
|
|
- OAuth / SSO / RBAC
|
|||
|
|
|
|||
|
|
## 当前 auth 模型
|
|||
|
|
|
|||
|
|
- 认证方式：`username/password`
|
|||
|
|
- 会话方式：server-side session
|
|||
|
|
- 客户端凭据：session cookie
|
|||
|
|
- 页面形态：Jinja server-side template
|
|||
|
|
|
|||
|
|
## 当前持久化
|
|||
|
|
|
|||
|
|
当前新增一个共享 App DB：
|
|||
|
|
|
|||
|
|
- `APP_DATABASE_URL`
|
|||
|
|
- 默认值：`sqlite:///./data/app.db`
|
|||
|
|
|
|||
|
|
当前 auth 相关数据存放在这个 DB 中：
|
|||
|
|
|
|||
|
|
- `auth_users`
|
|||
|
|
- `auth_sessions`
|
|||
|
|
|
|||
|
|
当前没有把 auth 数据和 `location` / `poo` DB 混放。
|
|||
|
|
|
|||
|
|
当前这部分现在也走 Alembic 管理：
|
|||
|
|
|
|||
|
|
- Alembic 环境：`alembic_app.ini` + `alembic_app/`
|
|||
|
|
- 初始化脚本：`python scripts/app_db_adopt.py`
|
|||
|
|
|
|||
|
|
当前没有 legacy app DB，所以这一版脚本只负责初始化新库，不负责 legacy adoption。
|
|||
|
|
|
|||
|
|
## 首次启动与 bootstrap
|
|||
|
|
|
|||
|
|
如果 auth DB 中还没有任何用户，应用启动时会要求：
|
|||
|
|
|
|||
|
|
- `AUTH_BOOTSTRAP_USERNAME`
|
|||
|
|
- `AUTH_BOOTSTRAP_PASSWORD`
|
|||
|
|
|
|||
|
|
并创建首个 admin 用户。
|
|||
|
|
|
|||
|
|
当前默认 bootstrap 值就是：
|
|||
|
|
|
|||
|
|
- username: `admin`
|
|||
|
|
- password: `admin`
|
|||
|
|
|
|||
|
|
首次登录后，系统会强制要求修改密码。
|
|||
|
|
|
|||
|
|
如果你希望在首次启动前就覆盖默认值，可以直接设置环境变量：
|
|||
|
|
|
|||
|
|
- `AUTH_BOOTSTRAP_USERNAME`
|
|||
|
|
- `AUTH_BOOTSTRAP_PASSWORD`
|
|||
|
|
|
|||
|
|
建议流程是：
|
|||
|
|
|
|||
|
|
1. 配好 `.env`
|
|||
|
|
2. 运行 `python scripts/app_db_adopt.py`
|
|||
|
|
3. 启动应用
|
|||
|
|
4. 用 `admin / admin` 首次登录
|
|||
|
|
5. 立即修改密码
|
|||
|
|
|
|||
|
|
## 安全设计
|
|||
|
|
|
|||
|
|
当前这版已经落实的基础安全点：
|
|||
|
|
|
|||
|
|
- 密码不明文存储，使用 scrypt 哈希
|
|||
|
|
- session cookie 为 `HttpOnly`
|
|||
|
|
- cookie 使用 `SameSite=Lax`
|
|||
|
|
- `Secure` cookie 在非 `development` 环境默认开启
|
|||
|
|
- 登录表单与登出表单都有基础 CSRF 校验
|
|||
|
|
- session token 为随机生成，服务端只持久化 token hash
|
|||
|
|
- session 有过期时间与显式失效机制
|
|||
|
|
|
|||
|
|
## 当前受保护范围
|
|||
|
|
|
|||
|
|
当前这轮只保护了页面入口：
|
|||
|
|
|
|||
|
|
- `GET /admin`
|
|||
|
|
- `POST /admin/change-password`
|
|||
|
|
- `POST /logout`
|
|||
|
|
|
|||
|
|
相关流程：
|
|||
|
|
|
|||
|
|
- `GET /login`
|
|||
|
|
- `POST /login`
|
|||
|
|
|
|||
|
|
未登录访问 `/admin` 时会被重定向到 `/login`。
|
|||
|
|
|
|||
|
|
## 下一步不在本轮内
|
|||
|
|
|
|||
|
|
后续可以在这个基座上继续做：
|
|||
|
|
|
|||
|
|
- 配置页面接入
|
|||
|
|
- config persistence
|
|||
|
|
- 更细的受保护路由范围
|
|||
|
|
- 用户初始化 / 密码轮换的更正式 runbook
|