# 基础鉴权说明

本文档说明当前 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