跳转至

快速接入自己的项目

新服务需要统一账号发现与宿主页入口时,优先阅读新服务接入:完整 factory、/admin 前缀、齿轮/链接菜单及 headless 接法。

  • 新建 FastAPI 网站:复制下方完整应用,先完成一次真实登录。
  • 已有账户数据库:保留账户与密码材料,换用 同步或异步回调。
  • 已有前端:保留页面,只挂载 ui=None 的 JSON 接口,按 浏览器契约 传递会话与 CSRF。
  • 先选视觉风格:运行 演示站 的模板游乐场,再复制 LoginUI(...) 配置。
  • 应用需要用户目录:使用 托管用户 的 owner/admin/user 预设,不把业务数据授权交给角色本身。

托管用户快速开始(0.2.0)

新应用需要自管账户时,显式依赖 ChatLogin>=0.2.0,<0.3.0。先由可信操作员在安全环境中提供 APP_BOOTSTRAP_CREDENTIAL,再把环境变量名交给 bootstrap;不要把凭据值写入命令行:

chatlogin users bootstrap operator --instance my-site --password-env APP_BOOTSTRAP_CREDENTIAL

然后用 create_managed_auth(instance="my-site", origin=...) 挂载默认登录、用户管理和本人资料页面。完整的角色矩阵、模板/headless 选择、owner 交接与会话失效说明见托管用户。此路径不迁移已有账户库;固定账号、回调和 ChatVoice adapter 继续按原方式接入。

1. 安装并保存完整应用

python -m pip install "ChatLogin[web]" uvicorn

把下面代码保存为 app.py。账号名为 operator,密码必须由你显式设置;示例不会读取演示站账号,也没有默认生产密码。

"""Minimal host app; provide an explicit password through the environment."""
import os
from urllib.parse import urlsplit

from fastapi import Depends, FastAPI
import uvicorn
from chatlogin import MemorySessionStore, PasswordBackend, Principal, SessionManager, hash_password
from chatlogin.fastapi import CookieSettings, FastAPIAuth
from chatlogin.ui import LoginUI

origin = os.environ.get("MY_SITE_ORIGIN", "http://127.0.0.1:8000")
password = os.environ["MY_SITE_LOGIN_PASSWORD"]
backend = PasswordBackend({
    "operator": (Principal("operator", "Operator"), hash_password(password)),
})
app = FastAPI()
auth = FastAPIAuth(
    backend,
    SessionManager(MemorySessionStore(max_sessions=256), instance="my-site", ttl=3600),
    origin=origin,
    ui=LoginUI(),
    cookie=CookieSettings(secure=urlsplit(origin).scheme == "https"),
)
app.include_router(auth.router)

@app.get("/")
def home():
    return {"login": "/auth/?next=/private"}

@app.get("/private")
def private(user=Depends(auth.current_user)):
    return user.as_dict()

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000, proxy_headers=False)

2. 显式设置密码并启动

在 Bash/Zsh 终端输入下面命令,再输入不少于 12 个字符的测试密码。输入不回显,密码不会进入命令行参数。

read -rs MY_SITE_LOGIN_PASSWORD
export MY_SITE_LOGIN_PASSWORD
python app.py

打开 http://127.0.0.1:8000/auth/?next=/private,使用 operator 与刚设置的密码登录。成功后 /private 返回服务端可信用户信息;未登录直接访问该路径返回 401。

这个示例使用单进程内存会话,重启即清空。生产部署应选择持久化 store、固定 HTTPS origin 和符合业务的数据权限;不能把公开演示身份搬进真实网站。

3. 保留后端,独立选择前端

你希望保留什么 修改方式 宿主负责什么
直接使用默认 UI ui=LoginUI(palette="forest", layout="split") 账户来源、业务路由
自有模板与品牌 LoginUI(template_dirs=("templates",), template_name="host/login.html") 模板安全、静态资源
原有 HTML/JS ui=None 表单、错误反馈、登录后的跳转
标准库 HTTP 宿主 LoginUI.render(context) Cookie、Origin、CSRF 与 HTTP 路由

template_dirs 是宿主可信模板目录,必须存在;不要修改 site-packages。模板覆盖和回调账户库互相独立。script_url 可指定同源本地脚本,默认不加载宿主脚本。

4. Headless 请求顺序

  1. GET /auth/session,匿名时也返回 200 与 authenticated=false。
  2. POST /auth/login,JSON 包含 username、password、next。浏览器自动发送同源 Origin;如果已有有效会话,先读取当前 CSRF,并加入 X-CSRF-Token。
  3. 使用 credentials: 'same-origin' 调用业务接口;Cookie 自动携带,不要手工读取 token。
  4. 写操作使用当前 CSRF;退出前重新读取 session,再 POST /auth/logout。
  5. 退出后清理私有界面;受保护接口恢复 401。

完整可运行的前端实现可以查看包内 chatlogin.demo_site/assets/demo.js 的 Headless 演示。公开 Demo 的业务数据是合成数据,不代表你的后端已经接入。

下一步

  • 接入与安全:四类后端、精确 ChatVoice schema、HTTP/角色/owner 边界。
  • Python 接口树:可导入的类与实际方法。
  • 托管用户:应用自管账户、角色矩阵、首个 owner 与默认 Web 预设。
  • 演示站:启动独立演示和查看配置效果。