home-automation/docs/auth.md

基础鉴权说明

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