121 lines
2.7 KiB
Markdown
121 lines
2.7 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`
|
||
- `app_config`
|
||
|
||
当前没有把 auth 数据和 `location` / `poo` DB 混放。
|
||
|
||
当前这部分现在也走 Alembic 管理：
|
||
|
||
- Alembic 环境：`alembic_app.ini` + `alembic_app/`
|
||
- 初始化脚本：`python scripts/app_db_adopt.py`
|
||
|
||
当前没有 legacy app DB，所以这一版脚本只负责初始化新库，不负责 legacy adoption。
|
||
|
||
`app_config` 现在承接运行时配置持久化。
|
||
|
||
其中：
|
||
|
||
- `.env` 负责 bootstrap / fallback
|
||
- `app_config` 表负责运行时配置覆盖
|
||
- 登录密码仍然属于认证数据，使用 Argon2 哈希，不存进 `app_config`
|
||
|
||
## 首次启动与 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. 立即修改密码
|
||
|
||
## 安全设计
|
||
|
||
当前这版已经落实的基础安全点：
|
||
|
||
- 密码不明文存储，使用 Argon2 哈希
|
||
- session cookie 为 `HttpOnly`
|
||
- cookie 使用 `SameSite=Lax`
|
||
- `Secure` cookie 在非 `development` 环境默认开启
|
||
- 登录表单与登出表单都有基础 CSRF 校验
|
||
- session token 为随机生成，服务端只持久化 token hash
|
||
- session 有过期时间与显式失效机制
|
||
|
||
## 当前受保护范围
|
||
|
||
当前这轮只保护了页面入口：
|
||
|
||
- `GET /config`
|
||
- `POST /config`
|
||
- `POST /config/change-password`
|
||
- `POST /logout`
|
||
|
||
相关流程：
|
||
|
||
- `GET /login`
|
||
- `POST /login`
|
||
|
||
未登录访问 `/config` 时会被重定向到 `/login`。
|
||
|
||
## 下一步不在本轮内
|
||
|
||
后续可以在这个基座上继续做：
|
||
|
||
- 配置页面接入
|
||
- config persistence
|
||
- 更细的受保护路由范围
|
||
- 用户初始化 / 密码轮换的更正式 runbook
|