mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-05-21 23:46:50 +00:00
greatmengqi
3e6a34297d
Squashes 25 PR commits onto current main. AppConfig becomes a pure value object with no ambient lookup. Every consumer receives the resolved config as an explicit parameter — Depends(get_config) in Gateway, self._app_config in DeerFlowClient, runtime.context.app_config in agent runs, AppConfig.from_file() at the LangGraph Server registration boundary. Phase 1 — frozen data + typed context - All config models (AppConfig, MemoryConfig, DatabaseConfig, …) become frozen=True; no sub-module globals. - AppConfig.from_file() is pure (no side-effect singleton loaders). - Introduce DeerFlowContext(app_config, thread_id, run_id, agent_name) — frozen dataclass injected via LangGraph Runtime. - Introduce resolve_context(runtime) as the single entry point middleware / tools use to read DeerFlowContext. Phase 2 — pure explicit parameter passing - Gateway: app.state.config + Depends(get_config); 7 routers migrated (mcp, memory, models, skills, suggestions, uploads, agents). - DeerFlowClient: __init__(config=...) captures config locally. - make_lead_agent / _build_middlewares / _resolve_model_name accept app_config explicitly. - RunContext.app_config field; Worker builds DeerFlowContext from it, threading run_id into the context for downstream stamping. - Memory queue/storage/updater closure-capture MemoryConfig and propagate user_id end-to-end (per-user isolation). - Sandbox/skills/community/factories/tools thread app_config. - resolve_context() rejects non-typed runtime.context. - Test suite migrated off AppConfig.current() monkey-patches. - AppConfig.current() classmethod deleted. Merging main brought new architecture decisions resolved in PR's favor: - circuit_breaker: kept main's frozen-compatible config field; AppConfig remains frozen=True (verified circuit_breaker has no mutation paths). - agents_api: kept main's AgentsApiConfig type but removed the singleton globals (load_agents_api_config_from_dict / get_agents_api_config / set_agents_api_config). 8 routes in agents.py now read via Depends(get_config). - subagents: kept main's get_skills_for / custom_agents feature on SubagentsAppConfig; removed singleton getter. registry.py now reads app_config.subagents directly. - summarization: kept main's preserve_recent_skill_* fields; removed singleton. - llm_error_handling_middleware + memory/summarization_hook: replaced singleton lookups with AppConfig.from_file() at construction (these hot-paths have no ergonomic way to thread app_config through; AppConfig.from_file is a pure load). - worker.py + thread_data_middleware.py: DeerFlowContext.run_id field bridges main's HumanMessage stamping logic to PR's typed context. Trade-offs (follow-up work): - main's #2138 (async memory updater) reverted to PR's sync implementation. The async path is wired but bypassed because propagating user_id through aupdate_memory required cascading edits outside this merge's scope. - tests/test_subagent_skills_config.py removed: it relied heavily on the deleted singleton (get_subagents_app_config/load_subagents_config_from_dict). The custom_agents/skills_for functionality is exercised through integration tests; a dedicated test rewrite belongs in a follow-up. Verification: backend test suite — 2560 passed, 4 skipped, 84 failures. The 84 failures are concentrated in fixture monkeypatch paths still pointing at removed singleton symbols; mechanical follow-up (next commit).
130 lines
3.7 KiB
Markdown
130 lines
3.7 KiB
Markdown
# Authentication Upgrade Guide
|
||
|
||
DeerFlow 内置了认证模块。本文档面向从无认证版本升级的用户。
|
||
|
||
## 核心概念
|
||
|
||
认证模块采用**始终强制**策略：
|
||
|
||
- 首次启动时自动创建 admin 账号，随机密码打印到控制台日志
|
||
- 认证从一开始就是强制的，无竞争窗口
|
||
- 历史对话（升级前创建的 thread）自动迁移到 admin 名下
|
||
|
||
## 升级步骤
|
||
|
||
### 1. 更新代码
|
||
|
||
```bash
|
||
git pull origin main
|
||
cd backend && make install
|
||
```
|
||
|
||
### 2. 首次启动
|
||
|
||
```bash
|
||
make dev
|
||
```
|
||
|
||
控制台会输出：
|
||
|
||
```
|
||
============================================================
|
||
Admin account created on first boot
|
||
Email: admin@deerflow.dev
|
||
Password: aB3xK9mN_pQ7rT2w
|
||
Change it after login: Settings → Account
|
||
============================================================
|
||
```
|
||
|
||
如果未登录就重启了服务，不用担心——只要 setup 未完成，每次启动都会重置密码并重新打印到控制台。
|
||
|
||
### 3. 登录
|
||
|
||
访问 `http://localhost:2026/login`，使用控制台输出的邮箱和密码登录。
|
||
|
||
### 4. 修改密码
|
||
|
||
登录后进入 Settings → Account → Change Password。
|
||
|
||
### 5. 添加用户（可选）
|
||
|
||
其他用户通过 `/login` 页面注册，自动获得 **user** 角色。每个用户只能看到自己的对话。
|
||
|
||
## 安全机制
|
||
|
||
| 机制 | 说明 |
|
||
|------|------|
|
||
| JWT HttpOnly Cookie | Token 不暴露给 JavaScript，防止 XSS 窃取 |
|
||
| CSRF Double Submit Cookie | 所有 POST/PUT/DELETE 请求需携带 `X-CSRF-Token` |
|
||
| bcrypt 密码哈希 | 密码不以明文存储 |
|
||
| 多租户隔离 | 用户只能访问自己的 thread |
|
||
| HTTPS 自适应 | 检测 `x-forwarded-proto`，自动设置 `Secure` cookie 标志 |
|
||
|
||
## 常见操作
|
||
|
||
### 忘记密码
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 重置 admin 密码
|
||
python -m app.gateway.auth.reset_admin
|
||
|
||
# 重置指定用户密码
|
||
python -m app.gateway.auth.reset_admin --email user@example.com
|
||
```
|
||
|
||
会输出新的随机密码。
|
||
|
||
### 完全重置
|
||
|
||
删除用户数据库，重启后自动创建新 admin：
|
||
|
||
```bash
|
||
rm -f backend/.deer-flow/users.db
|
||
# 重启服务，控制台输出新密码
|
||
```
|
||
|
||
## 数据存储
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `.deer-flow/users.db` | SQLite 用户数据库（密码哈希、角色） |
|
||
| `.env` 中的 `AUTH_JWT_SECRET` | JWT 签名密钥（未设置时自动生成临时密钥，重启后 session 失效） |
|
||
|
||
### 生产环境建议
|
||
|
||
```bash
|
||
# 生成持久化 JWT 密钥，避免重启后所有用户需重新登录
|
||
python -c "import secrets; print(secrets.token_urlsafe(32))"
|
||
# 将输出添加到 .env：
|
||
# AUTH_JWT_SECRET=<生成的密钥>
|
||
```
|
||
|
||
## API 端点
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/v1/auth/login/local` | POST | 邮箱密码登录（OAuth2 form） |
|
||
| `/api/v1/auth/register` | POST | 注册新用户（user 角色） |
|
||
| `/api/v1/auth/logout` | POST | 登出（清除 cookie） |
|
||
| `/api/v1/auth/me` | GET | 获取当前用户信息 |
|
||
| `/api/v1/auth/change-password` | POST | 修改密码 |
|
||
| `/api/v1/auth/setup-status` | GET | 检查 admin 是否存在 |
|
||
|
||
## 兼容性
|
||
|
||
- **标准模式**（`make dev`）：完全兼容，admin 自动创建
|
||
- **Gateway 模式**（`make dev-pro`）：完全兼容
|
||
- **Docker 部署**：完全兼容，`.deer-flow/users.db` 需持久化卷挂载
|
||
- **IM 渠道**（Feishu/Slack/Telegram）：通过 LangGraph SDK 通信，不经过认证层
|
||
- **DeerFlowClient**（嵌入式）：不经过 HTTP，不受认证影响
|
||
|
||
## 故障排查
|
||
|
||
| 症状 | 原因 | 解决 |
|
||
|------|------|------|
|
||
| 启动后没看到密码 | admin 已存在（非首次启动） | 用 `reset_admin` 重置，或删 `users.db` |
|
||
| 登录后 POST 返回 403 | CSRF token 缺失 | 确认前端已更新 |
|
||
| 重启后需要重新登录 | `AUTH_JWT_SECRET` 未持久化 | 在 `.env` 中设置固定密钥 |
|