LobeChat + Logto + MinIO

Next.js 在这个项目里不是渲染前端页面的（前端是 Vite SPA），它的角色是后端 HTTP 服务器。tRPC 是类型安全的 API 框架。

Next.js 16 App Router — HTTP 服务器

src/app/(backend)/trpc/lambda/[trpc]/route.ts:9-37：

const handler = (req: NextRequest) => {
  return fetchRequestHandler({
    createContext: () => createLambdaContext(req),
    endpoint: '/trpc/lambda',
    router: lambdaRouter,    // 47 个子路由
  });
};
export { handler as GET, handler as POST };

App Router 的 route.ts = 一个 HTTP 端点。LobeChat 用它做了：

• /trpc/lambda/[trpc] → tRPC API（主业务，47 路由）
• /api/auth/[...all] → Better Auth 认证
• /webapi/admin/users → 管理 API
• /f/[id] → 文件代理（302 到 S3 预签名 URL）
• /spa/[variants]/[[...path]] → SPA HTML 模板服务

Next.js = Express/Koa 的替代品，接收 HTTP 请求、路由分发、返回响应。

tRPC v11.8 — 类型安全 API

前后端共享 TypeScript 类型，前端调 API 像调本地函数，不需要手写 fetch。

src/libs/trpc/lambda/index.ts:26-31 — 两种 procedure：

export const publicProcedure = baseProcedure;
// 只有 OpenTelemetry 追踪

export const authedProcedure = baseProcedure
  .use(oidcAuth)    // OIDC JWT 验证
  .use(userAuth);   // Better Auth 会话验证

src/server/routers/lambda/file.ts:27-39 — 实际路由示例：

const fileProcedure = authedProcedure  // 必须登录
  .use(serverDatabase)                  // 注入 DB 连接
  .use(async (opts) => {
    return opts.next({ ctx: {
      fileModel: new FileModel(ctx.serverDB, ctx.userId),
      fileService: new FileService(ctx.serverDB, ctx.userId),
    }});                                // 注入业务模型
  });

认证上下文怎么来的

src/libs/trpc/lambda/context.ts:113-244 — 三种认证按优先级：

请求进来 → createLambdaContext(request)
 ├─ 有 X-API-Key? → 查 DB 验证 → userId    // line 152-172
 ├─ OIDC 启用 + Oidc-Auth header?
 │   → 验证 JWT → userId                    // line 178-203
 └─ 都没有? → Better Auth Cookie
     → auth.api.getSession() → userId       // line 216-226

两者关系

浏览器: POST /trpc/lambda/file.createFile
  ▼
Next.js App Router        ← 接收 HTTP，匹配 route.ts
  ▼
fetchRequestHandler()     ← tRPC 适配器，解析请求
  ▼
createLambdaContext()     ← 认证（API Key / OIDC / Cookie）
  ▼
tRPC Router               ← file.createFile procedure
  │  Zod 校验 → 中间件链 → 业务逻辑
  ▼
返回 JSON                  ← Next.js 发回浏览器

一句话：Next.js = HTTP 收发室，tRPC = 内部调度中心（路由 + 认证 + 校验 + 类型安全）。

---

追问：认证不是 Logto 做的吗？tRPC 中间件为什么还要认证？

它们管的是完全不同的阶段：

第 1 层：Logto — "你是谁？"（只管登录那一次）

用户点击 "使用 Logto 登录"
→ 跳转 Logto 页面 → 输入账号密码 → Logto 验证通过
→ 发回 authorization_code → 浏览器带 code 回到 LobeChat
→ Logto 的工作到此结束，后续不再参与任何请求。

第 2 层：Better Auth — "发通行证"（登录后建会话）

Better Auth 用 code 换 access_token + id_token
→ 解析 id_token 拿到 email/name
→ DB 创建/关联用户 → 创建 Session（30 天有效）
→ Set-Cookie: better-auth.session_token=xxx
→ 写入 Redis 缓存（10 分钟）

第 3 层：tRPC 中间件 — "每个请求都验票"

用户每次调 API，浏览器自动带 Cookie。tRPC 中间件每次都验证：

context.ts:216-226：

const session = await auth.api.getSession({
  headers: request.headers,   // 包含 Cookie
});
if (session?.user?.id) {
  userId = session.user.id;   // 有效 → 拿到 userId
}

userAuth.ts:5-17：

if (!ctx.userId) {
  throw new TRPCError({ code: 'UNAUTHORIZED' }); // 无效 → 拒绝
}
return opts.next({ ctx: { userId: ctx.userId } }); // 有效 → 放行

为什么每次都要验？

• Cookie 可能过期（30 天后）
• Cookie 可能被篡改
• 用户可能被管理员 banned 了
• 请求可能根本没带 Cookie（爬虫/攻击）

不验 → 任何人能调 API 上传文件、读别人聊天记录。

三层配合流程

【Logto — 只在登录时出现一次】
用户 → Logto 登录 → 验证身份 → 返回 code

【Better Auth — 登录时建会话】
code → 换 token → 创建 Session → Set-Cookie

【tRPC 中间件 — 之后每个请求都验票】
POST /trpc/lambda/message.create (自动带 Cookie)
  → context.ts: auth.api.getSession(headers)
    → Redis 命中? → 直接拿 userId（不查 DB，快）
    → 未命中? → 查 sessions 表 → 刷新缓存
  → userAuth: userId 存在?
    → 是 → 注入 ctx，执行业务逻辑
    → 否 → 401 拒绝
  → 业务: new MessageModel(db, userId) → 只能操作自己的数据

一句话：Logto = 门卫（验身份，只来一次），Better Auth = 前台（发通行证），tRPC 中间件 = 每道门的保安（每次请求都验票）。三层缺一不可。

不多余。"进来了"只是浏览器拿到了一个 Cookie，但服务器不信任浏览器。

源码证据 — src/server/routers/lambda/file.ts:27-38：

const fileProcedure = authedProcedure.use(async (opts) => {
  return opts.next({ ctx: {
    fileModel: new FileModel(ctx.serverDB, ctx.userId),
    //                                     ↑ 从哪来？
  }});
});

FileModel 所有查询都用 userId 过滤——你只能读写自己的数据。这个 userId 不是前端传的（可以伪造），是服务器从 Cookie 里验出来的。

tRPC 中间件做的不是"再次登录"，而是"从 Cookie 里提取可信的 userId 给业务代码用"。

每次验的理由：

• Cookie 可以伪造 — 攻击者手动构造请求
• Session 会过期 — 30 天后失效
• 用户可能被 ban — 管理员刚操作的
• CSRF 攻击 — 别的网站偷偷用你的 Cookie 发请求

如果不验：

POST /trpc/lambda/file.getFiles（伪造请求）
→ 没有 userId → FileModel(db, undefined)
→ 查到所有人的文件 → 数据泄露

完全可以实现，源码已经铺好了 RBAC 基础设施，只差最后一步接入。

已经建好的：4 张 RBAC 表

packages/database/src/schemas/rbac.ts：

rbac_roles            — 角色（admin, user, guest...）
rbac_permissions      — 权限（agent:create, file:upload...）
rbac_role_permissions — 角色↔权限关联
rbac_user_roles       — 用户↔角色关联（支持临时角色 expiresAt）

已经定义的：56 个细粒度权限

packages/const/src/rbac.ts:8-156：

agent:read/create/delete/update/fork
ai_model:read/create/delete/update/invoke
file:read/upload/update/delete
message:read/create/update/delete
session:read/create/update/delete
knowledge_base:read/create/update/delete
user:read/create/update/delete
rbac:role_create/role_delete/user_role_update...

每个权限还有 scope（rbac.ts:161）：ALL（管所有人的）和 OWNER（只管自己的）。

已经写好的：RBAC Model

packages/database/src/models/rbac.ts:89-110：

rbacModel.hasPermission('file:upload')     // 检查单个权限
rbacModel.hasAnyPermission([...])          // OR 逻辑
rbacModel.hasAllPermissions([...])         // AND 逻辑
rbacModel.getUserRoles()                   // 查角色
rbacModel.updateUserRoles(userId, roleIds) // 改角色

还没接上的：tRPC 主业务路由

RbacModel 只在 packages/openapi/src/common/base.controller.ts:195 使用（OpenAPI 层），47 个 tRPC 路由里没有一个检查 RBAC 权限。

当前状态：认证只到 userId —— 知道"你是谁"，但不检查"你能干什么"。所有用户登录后功能完全相同。

实现只差一步：写一个 tRPC 中间件

// 类似 src/libs/trpc/middleware/userAuth.ts
export const requirePermission = (code: string) =>
  trpc.middleware(async (opts) => {
    const rbacModel = new RbacModel(ctx.serverDB, ctx.userId);
    if (!(await rbacModel.hasPermission(code)))
      throw new TRPCError({ code: 'FORBIDDEN' });
    return opts.next();
  });

// 用法：
const adminProcedure = authedProcedure
  .use(serverDatabase)
  .use(requirePermission('user:read:all'));

完整实现路径

1. 写 requirePermission tRPC 中间件
2. 初始化 RBAC 数据（往 4 张表里插角色+权限+关联）
3. 在需要控制的路由上加中间件（如 aiProvider 路由加 ai_provider:update:all）
4. 前端设置页面：用 tRPC lambdaQuery 而不是裸 fetch('/webapi/...')
5. 重新 pnpm run build

没有任何源码阻止这个。表有了、Model 有了、56 个权限定义了、scope 逻辑写了——只差一个中间件把它们串进 tRPC。

不会自动显示。前后端都要改，没有"改一边另一边自动好"的机制。

前端显示一个设置 Tab 要过 4 关

SettingsContent.tsx:36：

const Component = componentMap[tab] || componentMap.appearance;
// URL 的 :tab → 查 componentMap → 有就渲染

_layout/Body/index.tsx:14,43-68：

const categoryGroups = useCategory();       // line 14
{categoryGroups.map(group =>               // line 43
  group.items.map(item =>
    <NavItem active={activeTab === item.key} />
  )
)}
// 侧边栏直接遍历 useCategory() 渲染菜单

为什么没显示？

这 4 关全在 Vite SPA 里。生产环境用的是冻结的 spaHtmlTemplates.ts——没跑 pnpm run build，改了等于没改。

正确顺序

1. 后端：写 tRPC router + RBAC 中间件
2. 前端：组件改用 lambdaQuery.admin.xxx.useQuery()
3. 菜单：useCategory.tsx 加 admin 判断
4. 构建：pnpm run build
5. 部署

前后端 + 构建，三步缺一不可。

源码里已经有两套控制机制，而且支持按用户 ID 控制，但缺一个管理员界面串起来。

第 1 套：Feature Flags（17 个功能开关）

src/config/featureFlags/schema.ts:6-39：

market           — 发现市场
knowledge_base   — 知识库
ai_image         — AI 生图
speech_to_text   — 语音转文字
edit_agent       — 编辑 Agent
api_key_manage   — API Key 管理
provider_settings — AI 服务商设置
changelog        — 更新日志
welcome_suggest  — 欢迎建议
token_counter    — Token 计数器
check_updates    — 检查更新
rag_eval         — RAG 评估
commercial_hide_github — 隐藏 GitHub 链接
commercial_hide_docs   — 隐藏文档链接
...

关键发现：支持按用户 ID 控制

schema.ts:4,49-58：

// 每个开关支持两种值：
const FeatureFlagValue = z.union([
  z.boolean(),          // true/false → 全局开关
  z.array(z.string())   // ['user_id_1', 'user_id_2'] → 只对这些人开
]);

// 判断逻辑：
const evaluateFeatureFlag = (flagValue, userId) => {
  if (typeof flagValue === 'boolean') return flagValue;
  if (Array.isArray(flagValue)) {
    return userId ? flagValue.includes(userId) : false;
  }
};

环境变量配法（FEATURE_FLAGS）：

# 全局关闭 AI 生图
FEATURE_FLAGS="-ai_image"

# 只对特定用户开启 API Key 管理
FEATURE_FLAGS="+api_key_manage:user_id_1,user_id_2"

第 2 套：useCategory 条件渲染

useCategory.tsx 里已有的条件判断（git show HEAD 原始源码）：

为什么没用起来？

这两套机制都是环境变量级的——配一次，要么全局生效，要么在环境变量里硬编码用户 ID。没有管理员界面让你在页面上勾选"张三能看什么"。

而且 Feature Flags 只控制了 17 个功能，useCategory.tsx 里的大部分菜单（技能管理、凭证管理、数据存储、高级设置）没有任何条件判断，对所有人都显示。

已有的完整基础设施清单

结论：基础设施全有，缺的是最后一层——管理员界面把 Feature Flags + RBAC + useCategory 串起来，让管理员在页面上动态控制。

Sharp 是 Node.js 图片处理库（基于 libvips，比 Canvas/Jimp 快 10 倍+）。LobeChat 里只在 AI 生图/视频场景用，聊天功能完全不涉及。

1. AI 生成图片 → 缩略图

src/server/services/generation/index.ts:113-137：

const sharpInstance = sharp(originalImageBuffer);  // line 113
const { format, width, height } = await sharpInstance.metadata(); // 读宽高

const thumbnailBuffer = shouldResize
  ? await sharpInstance.resize(w, h).webp().toBuffer() // 缩小+转 WebP
  : originalImageBuffer;                                // 不需要缩就直接用

AI 生成一张图 → Sharp 读元数据 + 生成 WebP 缩略图 → 原图+缩略图都传 S3。

2. AI 生成视频 → 封面处理

src/server/services/generation/video.ts:97,110-115：

sharp(coverBuffer).webp({ quality: 100 })                   // 封面转 WebP
sharp(coverBuffer).resize(w, h, { fit: 'inside' }).webp()   // 封面缩略图

3. ComfyUI 图片预处理

src/server/services/comfyui/core/imageService.ts:147-208：

sharp(buffer).metadata()                          // 读尺寸
sharp(buffer).resize(w, h, { fit: 'inside' })     // 按模型架构缩放

用户上传图给 ComfyUI 工作流前，按模型要求调整尺寸。

不用图片生成功能 → Sharp 永远不会被调到

Redis 在 LobeChat 里是加速器，干两件事，都不是必须的但没它会慢。

1. 会话缓存（加速"这个请求是谁发的"）

src/libs/better-auth/define-config.ts:180,190：

session: {
  cookieCache: { enabled: true, maxAge: 600 }, // 10 分钟
  storeSessionInDatabase: true,  // DB 兜底
},
secondaryStorage: createSecondaryStorage(), // ← Redis

src/libs/better-auth/utils/config.ts:74-110 — Redis 作为 Better Auth 的 secondaryStorage：

// key 格式: better-auth:{session_token}
get: (key) => redisClient.get(buildKey(key))
set: (key, value, ttl) => redisClient.set(buildKey(key), value, { ex: ttl })

每次 API 请求验身份：Redis 有 → 直接拿 userId（不查 DB）。Redis 没有 → 查 PostgreSQL sessions 表 → 写回 Redis。

2. 文件预签名 URL 缓存

src/app/(backend)/f/[id]/route.ts:13-17,44-52,76-80：

const FILE_PROXY_KEY_PREFIX = 'file-proxy:';
const PRESIGNED_URL_CACHE_TTL = 240;  // 缓存 4 分钟

// 访问 /f/{fileId} 时：
if (redisClient) {
  const cached = await redisClient.get(cacheKey);
  if (cached) return Response.redirect(cached, 302); // 命中 → 直接跳转
}
// 未命中 → 查 DB → 调 S3 生成 URL → 存 Redis
await redisClient.set(cacheKey, url, { ex: 240 });

URL 5 分钟过期，缓存 4 分钟（安全余量 1 分钟）。

没有 Redis 会怎样？

Claude Code 能读源码，但 LobeChat 太大（62 个包），上下文窗口装不下全部。它读了一部分就动手，漏掉了架构层面的关键文件。

铁证 1：直接用 Drizzle ORM —— 整个项目只有 AI 写的文件这么干

搜索 src/app/(backend)/webapi/ 下所有 route.ts：

项目规范是走 Service → Model → DB。AI 读了 schema（知道 users 表有 banned 字段），但没发现项目有 Service/Model 层的规范，直接手写 SQL。

铁证 2：import 了没用的东西

admin/users/route.ts:1：

import { and, eq, ne } from 'drizzle-orm';
// ne 在整个文件里根本没用过

AI 习惯性导入"可能用到的"操作符。

铁证 3：没走 checkAuth，自己手写认证

官方 webapi 路由用统一的 checkAuth 中间件。AI 写的代码直接 auth.api.getSession() 手写——能跑，但绕开了项目统一的认证层。说明不知道 checkAuth 存在。

铁证 4：不知道 RBAC 表存在

项目有完整的 RBAC 系统（4 张表 + 56 个权限 + Model），但 AI 写的代码直接查 users.role === 'admin' 做权限判断，完全没用 RBAC。说明没读到 packages/database/src/schemas/rbac.ts 和 packages/const/src/rbac.ts。

根本原因

不是"猜着写"——Claude Code 确实读了源码（路径别名、schema 字段都对）。问题是读了一部分就动手了：

• 读了 users schema → 知道有 role、banned 字段 ✓
• 读了 @/auth → 知道怎么获取 session ✓
• 没读 packages/const/src/rbac.ts → 不知道有 56 个权限定义 ✗
• 没读 packages/database/src/models/rbac.ts → 不知道有 RbacModel ✗
• 没读 src/app/(backend)/middleware/auth.ts → 不知道有 checkAuth ✗
• 没读 package.json:37 → 不知道双构建 ✗
• 没读 route.ts:89-99 → 不知道 SPA 模板是冻结的 ✗

62 个包、几十万行代码，上下文窗口装不下。不是你的问题，是任务超出了单次对话的理解范围。今天这次源码解析就是在补这个课——先读完架构再动手。

---

追问：但 boss 说他那边前端确实显示了，他说他改成了

Boss 的代码还没给过来，无法验证他的具体实现。但从源码架构看，只要跑了完整构建流程，前端按钮确实能显示——因为 Settings 路由是 :tab 通配的（desktopRouter.config.tsx:339），只需要 componentMap 里有对应组件就会渲染。

等他代码到了需要重点核查的：

Boss 发来的截图证实了他的实现（代码尚未拿到）：

源码佐证：他大概率只改了前端

逐项对比截图 vs 原始 useCategory.tsx 源码（git show HEAD:src/routes/(main)/settings/hooks/useCategory.tsx）：

普通用户看到的 6 项——全是源码自带的，不需要写新代码：

管理员多出的 7 项——6 项也是源码自带的：

他做的改动很可能只是在 useCategory.tsx 里加了角色判断：

// 原来：无条件显示
{ icon: SkillsIcon, key: SettingsTabs.Skill, label: '技能管理' },

// 改成：只有 admin 才显示
isAdmin && { icon: SkillsIcon, key: SettingsTabs.Skill, label: '技能管理' },

纯前端改动，不需要后端。前端藏菜单 ≠ 后端权限控制——普通用户直接访问 /settings/advanced URL 可能照样能进。

结论

不是你的问题。他的实现看起来多（13 项 vs 6 项），但实际上可能只改了 useCategory.tsx 一个文件——把原本所有人都能看的菜单加了 isAdmin && 条件。真正的后端 RBAC 权限控制大概率没做。等代码到了一看便知。

---

追问：能否做出管理员控制其他用户看到什么？

可以做，改动量不大。从源码看需要改 4 个点：

现在缺什么

UserInitializationState（packages/types/src/user/preference.ts:82-105）——前端初始化时拿到的用户数据没有 role 字段：

interface UserInitializationState {
  avatar, email, fullName, username,
  interests, preference, settings...
  // ← 没有 role！前端不知道你是不是管理员
}

4 步实现

第 1 步：后端把 role 传给前端

src/server/routers/lambda/user.ts:56-106 的 getUserState 返回值加 role：

return {
  avatar: state.avatar,
  email: state.email,
  // ... 原有字段
  role: state.role,  // ← 加这一行，DB users.role 已有
};

同时 UserInitializationState 接口加 role?: string。

第 2 步：前端 Store 自动有 role

getUserState 返回值写入 Zustand Store，加了字段自动可用。

第 3 步：useCategory.tsx 按 role 过滤

const role = useUserStore(s => s.user?.role);
const isAdmin = role === 'admin';

// 管理员才能看到的：
isAdmin && { icon: Brain, key: SettingsTabs.Provider },
isAdmin && { icon: SkillsIcon, key: SettingsTabs.Skill },
isAdmin && { icon: Database, key: SettingsTabs.Storage },
isAdmin && { icon: EllipsisIcon, key: SettingsTabs.Advanced },

第 4 步（可选）：管理员界面动态配置

让管理员在界面勾选"普通用户能看哪些菜单"→ 存 DB → useCategory 从服务端读配置。第一版硬编码 isAdmin 就够。

三个东西管数据的不同阶段，各有分工：

Zustand — 脑子（客户端状态）

src/store/chat/store.ts:75-78：

export const useChatStore = createWithEqualityFn<ChatStore>()(
  subscribeWithSelector(devtools(createStore)),
  shallow,
);

聊天消息列表、当前选中 Agent、侧边栏开关、主题色——纯客户端状态，改了立刻反映到 UI，不请求服务器。12 个 slice 组合成一个 Store（消息、线程、主题、AI 对话、插件、TTS 等）。

SWR — 管家（服务器数据拉取 + 自动刷新）

src/libs/swr/index.ts:14-38：

export const useClientDataSWR = (key, fetch, config) =>
  useSWR(key, fetch, {
    dedupingInterval: 0,
    focusThrottleInterval: 5 * 60 * 1000, // 5 分钟节流
    revalidateOnFocus: true,   // 切回窗口自动刷新
    revalidateOnReconnect: true, // 断网重连自动刷新
  });

会话列表、用户设置、主题列表——来自服务器的数据。SWR 负责首次拉取 + 自动刷新 + 缓存 + 错误重试。Store 的 action 里调 useSWR 拿数据，拿到后写入 Zustand。

React Query — tRPC 的底层（不是自己选的，是被迫带进来的）

src/libs/trpc/client/lambda.ts:3,159：

import { createTRPCReact } from '@trpc/react-query';
// ↑ tRPC 官方 React 包，内部就是 React Query，没得选

export const lambdaQuery = createTRPCReact<LambdaRouter>();

"强绑定"的意思：@trpc/react-query 内部用的就是 React Query 的 useQuery/useMutation，不能换成 SWR。

实际调法对比：

SWR 方式（老代码） — src/store/home/slices/agentList/action.ts:44-48：

useFetchAgentList = (isLogin) => {
  return useClientDataSWR(
    [FETCH_AGENT_LIST_KEY, isLogin],          // 手动定义 key
    () => homeService.getSidebarAgentList(),  // 手动写 fetch
  );
};
// 要自己写 key + fetch 函数 + service 层

tRPC 方式（新代码） — src/routes/(main)/settings/creds/features/CredsList.tsx:46-48：

const { data, isLoading, refetch } =
  lambdaQuery.market.creds.list.useQuery(undefined, {
    enabled: isAuthenticated,
  });
// 不需要写 fetch、不需要 key、不需要 service 层
// 参数和返回值自动有 TypeScript 类型

三者的分工

为什么不统一成一个？ 历史原因——SWR 是项目早期用的，后来引入 tRPC 时带来了 React Query（tRPC 强绑定）。两者并存，新代码逐步迁向 tRPC/React Query。

从源码看有三个卡点可能导致 Poe 类集合商配了没反应：

卡点 1：fetchOnClient 自动判断出错

src/store/aiInfra/slices/aiProvider/selectors.ts:90-96：

// 没填 baseURL 也没填 apiKey → 强制走服务端
if (!isProviderEndpointNotEmpty && !isProviderApiKeyNotEmpty)
  return false;

// 只填了 baseURL 没填 apiKey → 强制走浏览器直连
if (isProviderEndpointNotEmpty && !isProviderApiKeyNotEmpty)
  return true;  // ← 浏览器直连，跨域被拦！

Poe 需要 Key + baseURL 都填。如果只填了一个，请求可能被发到浏览器直连（跨域失败），或者走服务端但没 Key。

卡点 2：SSRF 保护拦截

packages/ssrf-safe-fetch/index.ts:32-33：

const envAllowPrivate =
  process.env.SSRF_ALLOW_PRIVATE_IP_ADDRESS === '1';
// 默认阻止私有 IP (192.168.x.x 等)

如果 Poe 走自建代理或内网地址 → SSRF 直接拦截。需要设 SSRF_ALLOW_PRIVATE_IP_ADDRESS=1。

卡点 3：非内置供应商默认当 OpenAI 处理

src/server/modules/ModelRuntime/index.ts:49-53：

const resolveRuntimeProvider = (provider, sdkType?) => {
  const isBuiltin = Object.values(ModelProvider)
    .includes(provider);
  if (isBuiltin) return provider;
  return sdkType || 'openai';  // ← 非内置 = OpenAI SDK
};

Poe 不在内置列表 → 用 OpenAI SDK 发请求。如果 Poe 的响应格式跟 OpenAI 有差异（流式格式、错误码），解析会失败。

正确配法

1. 在设置里添加自定义供应商，SDK 类型选 openai
2. 同时填 API Key 和 Base URL
3. 如果走内网代理：加环境变量 SSRF_ALLOW_PRIVATE_IP_ADDRESS=1
4. 确认 Poe 的 API 是否严格兼容 OpenAI 格式（特别是流式 SSE）

三个层面都有隔离，不会泄露。

Claude Prompt Caching

packages/model-runtime/src/core/anthropicCompatibleFactory/index.ts:152：

cache_control: enabledContextCaching
  ? { type: 'ephemeral' }  // ← 自动加缓存标记
  : undefined,

系统提示 + 工具定义自动加 cache_control。缓存在 Anthropic 服务端按 API Key 隔离，不会跨 Key 泄露。同一个 Key 下多用户的 system prompt 如果相同，会复用缓存节省 token。

Redis 缓存

LobeChat 的 Redis 只缓存两类数据：

• 会话：按 session_token 隔离，不同用户不同 token
• 文件代理 URL：按 file-proxy:{fileId} 隔离，fileId 全局唯一

LLM 请求本身

不经过任何缓存。每次调用都是独立的 HTTP 请求到供应商 API（initModelRuntimeFromDB 每次创建新 Runtime 实例）。不存在"张三的回答被李四看到"的可能。

LobeChat 有两级 API Key 来源，不会冲突，源码已为多用户共享设计。

第 1 级：环境变量（管理员配，全员共享兜底）

src/server/modules/ModelRuntime/index.ts:184：

const apiKey = apiKeyManager.pick(
  payload?.apiKey              // ← 用户自己的（DB 里）
  || llmConfig[`${upper}_API_KEY`]  // ← 环境变量的（兜底）
);

用户没配 Key → 自动用环境变量里的。你在 Docker 配 OPENAI_API_KEY=sk-xxx，全员共享。

第 2 级：用户个人 Key（DB 加密隔离）

packages/database/src/schemas/aiInfra.ts:17-51：

ai_providers 表:
  primaryKey = (id, userId)  // ← 每用户每供应商一条记录
  keyVaults = text           // ← 加密存储

张三的 OpenAI Key 和李四的完全独立，互不干扰。

初始化流程

initModelRuntimeFromDB()（index.ts:400-429）：

1. AiProviderModel(db, userId) → 按 userId 查 ai_providers
2. KeyVaultsGateKeeper.getUserKeyVaults → 解密 keyVaults
3. 用户有 Key? → 用用户的
4. 没有? → 回落到环境变量（line 184 的 || 逻辑）
5. initModelRuntimeWithUserPayload() → 创建该次请求的 Runtime

多人同时调不会冲突吗？

apiKeyManager.ts:9-46 — 支持多 Key 轮换：

# 环境变量支持逗号分隔多个 Key
OPENAI_API_KEY=sk-aaa,sk-bbb,sk-ccc

# 选择策略
API_KEY_SELECT_MODE=random  // 随机选（默认）
API_KEY_SELECT_MODE=turn    // 轮换

多人同时调 → apiKeyManager.pick() 自动分流到不同 Key → 避免单个 Key 打满速率限制。

本地模型（Ollama）

index.ts:190-194：

case ModelProvider.Ollama: {
  const baseURL = payload?.baseURL
    || process.env.OLLAMA_PROXY_URL;  // 只需要地址，不需要 Key
  return { baseURL };
}

配 OLLAMA_PROXY_URL=http://192.168.2.221:11434，所有用户共享本地模型。Ollama 本身支持并发请求队列，不会冲突。

结论

需要。认证不只是防外人，更是区分"你是谁"。

即使全是公司员工，服务器还是要知道：

• 这条消息是张三发的还是李四发的？
• 这个文件谁上传的？谁能删？
• API Key 配额扣谁的？
• 设置、聊天记录、收藏——按人隔离

没有 userId → 所有人数据混一起 → 公共匿名聊天室。

内网可以简化"登录方式"，不能去掉"验票"：

完全可以改，源码已预留二开机制，不是硬编码。改一个文件 + 替换几张图片即可。

核心控制文件（改这一处全局生效）

packages/business/const/src/branding.ts（41 行）：

export const BRANDING_NAME = 'LobeHub';      // ← 改成你的公司名
export const BRANDING_LOGO_URL = '';          // ← 填你的 Logo URL
export const ORG_NAME = 'LobeHub';            // ← 改成你的组织名

export const BRANDING_URL = { help, privacy, terms, ... };  // 链接
export const SOCIAL_URL = { discord, github, ... };          // 社交媒体
export const BRANDING_EMAIL = { business, support };         // 邮箱

源码自动检测二开

packages/const/src/version.ts:10-12：

export const isCustomBranding = BRANDING_NAME !== 'LobeHub';  // line 10
export const isCustomORG = ORG_NAME !== 'LobeHub';            // line 12

改了名字 → isCustomBranding = true → 全局 Logo 组件自动切换。

Logo 切换逻辑

src/components/Branding/ProductLogo/index.tsx:16-21：

if (isCustomBranding) {
  return <CustomLogo />;   // ← 用你的 Logo
}
return <LobeHub />;         // ← 默认 LobeHub

src/components/Branding/ProductLogo/Custom.tsx:34,45：

• BRANDING_LOGO_URL 有值 → 显示你的图片（支持 3d/flat/mono/text/combine 5 种模式）
• 为空 → 显示 BRANDING_NAME 粗体文字

src/components/Branding/OrgBrand/index.tsx:8-13：

if (isCustomORG) {
  return <span>{ORG_NAME}</span>;  // ← 纯文字
}
return <LobeHub />;

颜色系统（不是硬编码）

src/layout/GlobalProvider/AppTheme.tsx:107-111,159-162：

const [primaryColor, neutralColor] = useUserStore(s => [
  userGeneralSettingsSelectors.primaryColor(s),   // line 108
  userGeneralSettingsSelectors.neutralColor(s),    // line 109
]);
customTheme: {
  primaryColor: primaryColor ?? defaultPrimaryColor,  // line 161
  neutralColor: neutralColor ?? defaultNeutralColor,  // line 160
}

主色调通过 Zustand Store 读取用户设置（Settings > Appearance），每个用户可自定义。全局默认色改 defaultPrimaryColor。

还需手动替换的

结论：前后端没有强绑定。branding.ts 一个文件 + 替换几张图 → 重新 pnpm run build 即可。

不是"前端 = UI 界面"那么简单。LobeChat 的前端是一个完整的客户端应用程序，三个东西各司其职：

React 19 — 应用运行环境（不只是画按钮）

src/layout/SPAGlobalProvider/index.tsx:31-85 展示了 React 的真正角色——搭建 12 层 Provider 嵌套的运行环境：

Locale（国际化）
  → NextThemeProvider（主题）
    → AppTheme（样式引擎）
      → ServerConfigStoreProvider（服务端配置注入）
        → QueryProvider（数据请求 React Query）
          → AuthProvider（认证状态）
            → StoreInitialization（Zustand 状态初始化）
              → FaviconProvider → GroupWizardProvider
                → DragUploadProvider（拖拽上传）
                  → LazyMotion（动画引擎）
                    → StyleProvider → children（实际页面）

React 在这里是应用框架：管状态、主题、认证、国际化、动画、弹窗宿主，不仅仅是渲染 HTML。

Vite — 编译器 + 开发服务器

index.html:139：

<script type="module" src="/src/spa/entry.web.tsx"></script>

浏览器不认识 .tsx。Vite 做两件事：

• 开发时（vite.config.ts:106-113）：启动 9876 端口开发服务器，实时编译 + HMR；代理 /api、/trpc、/webapi 到 Next.js 3010
• 构建时（vite.config.ts:26-31）：打包到 dist/desktop/，base 路径变为 /spa/

为什么不用 Next.js 自带的构建？ 主界面是 SPA，不需要 SSR。Vite 构建 SPA 更快更轻。

React Router v7 — 客户端导航

src/spa/entry.web.tsx:17-22：

const router = createAppRouter(desktopRoutes, { basename });
createRoot(document.getElementById('root')!).render(
  <RouterProvider router={router} />
);

src/utils/router.tsx:175-186 —— 用 createBrowserRouter（纯客户端路由），URL 变化时匹配路由树，lazy() 按需加载页面，不向服务器发请求。

src/spa/router/desktopRouter.config.tsx:25 每个页面懒加载：

element: dynamicElement(() => import('@/routes/(main)/agent'), 'Desktop > Chat')

三者协作流程

用户访问 chat.example.com
  ▼
Next.js 服务端 (route.ts:190-227) → 返回 index.html + __SERVER_CONFIG__
  ▼
Vite 构建产物 (index.html:139) → <script src="/spa/assets/entry.web-xxxxx.js">
  ▼
React 19 启动 (entry.web.tsx:19) → createRoot → SPAGlobalProvider（12 层 Provider）
  ▼
React Router 接管 URL (entry.web.tsx:17) → createBrowserRouter → lazy import 页面
  ▼
之后所有跳转在浏览器内完成，只请求 tRPC 数据，不再请求 HTML

一句话：React = 运行环境，Vite = 编译器，React Router = 客户端导航。缺一不可。

即使重新构建，改动本身有 3 层问题导致功能无法正常工作：

问题 1：注册后立即登录会被自己的逻辑挡住

src/app/[variants]/(auth)/signin/page.tsx:68-85 的流程：

注册成功
→ fetch('/webapi/pending-approval', { userId })      // line 69-73
→ 把用户标记为 banned=true, banReason='pending'     // pending-approval/route.ts:40-43
→ 然后立刻 signIn.email({ email, password })        // line 76-80
→ Better Auth 检查 banned=true → 拒绝登录！

src/app/(backend)/webapi/pending-approval/route.ts:39-43 源码：

// 非第一个用户 → 标记为待审核
await serverDB.update(users)
  .set({ banned: true, banReason: 'pending' })   // line 42
  .where(eq(users.id, userId));

你刚把用户 banned 了，接着就登——Better Auth 会检查 banned 字段，直接拒绝。新用户永远卡在"注册了但登不进去"的死循环。

问题 2：signin 页面砍掉了原有认证框架的全部配置适配

原始的 useSignIn hook（src/app/[variants]/(auth)/signin/useSignIn.ts）包含完整逻辑：

如果服务端配 AUTH_SSO_PROVIDERS=logto，原页面会显示 Logto 按钮，你的页面直接无视。

而且你用 username@local.host 伪邮箱替代 email——Better Auth 内部有 normalizedEmail 归一化逻辑（packages/database/src/schemas/user.ts:15），伪邮箱可能不被正确处理。

问题 3：双构建都没做

你改了两套系统的代码，但两边都需要各自构建：

• signin/page.tsx + webapi/admin/ + webapi/pending-approval/ → Next.js 侧，需要 next build
• settings/user-management/ + componentMap.ts + useCategory.tsx + useNavLayout.ts → Vite SPA 侧，需要 vite build

只改源码不重建，Docker 容器里跑的还是旧的构建产物。即使重建一边，另一边也不会更新。

正确做法应该是

1. signin 页面：保留原有 useSignIn 框架，在其基础上扩展"用户名注册"逻辑，而不是全部重写
2. 注册审批：注册后不要立即 banned，而是先让用户正常登录，在 SPA 里通过 tRPC 中间件检查审批状态，显示"待审批"提示页
3. 后端 API：用 tRPC router（走 authedProcedure 中间件链）而不是裸 webapi Route Handler，这样自动获得认证 + 类型安全
4. 构建：改完后 pnpm run build 完整重建

LobeChat 采用 Next.js + Vite SPA 双构建架构，生产环境下 SPA 的 HTML 在构建时被"冻住"了。改源码不重新构建，页面不会变。

证据 1：生产 vs 开发的分支逻辑

src/app/spa/[variants]/[[...path]]/route.ts:89-99

async function getTemplate(isMobile) {
  if (isDev) {
    const res = await fetch(VITE_DEV_ORIGIN);       // line 91 — 实时拉
    return rewriteViteAssetUrls(await res.text());
  }
  const { desktopHtmlTemplate, mobileHtmlTemplate }
    = await import('./spaHtmlTemplates');             // line 96 — 冻结的字符串
  return isMobile ? mobileHtmlTemplate : desktopHtmlTemplate;
}

证据 2：spaHtmlTemplates.ts 怎么来的

scripts/generateSpaTemplates.mts:6,24

const desktopHtml = readFileSync(resolve(root, 'dist/desktop/index.html'), 'utf8');  // line 6
output = `export const desktopHtmlTemplate = ${JSON.stringify(desktopHtml)};`         // line 24

把 Vite 产物整个读成字符串写死到 .ts 文件。

证据 3：完整构建链

package.json:37

"build": "bun run build:spa && bun run build:spa:copy && bun run build:next"

1. build:spa (line 46) → vite build → dist/desktop/
2. build:spa:copy (line 44) → 复制 assets + 生成冻结 spaHtmlTemplates.ts
3. build:next (line 40) → next build

证据 4：开发模式两个进程

scripts/devStartupSequence.mts:119,126

nextProcess = spawn('npx', ['next', 'dev', '-p', 3010);  // line 119
viteProcess = runNpmScript('dev:spa');                     // line 126, 端口 9876

涉及的改动归类

结论：开发用 pnpm run dev，部署必须 pnpm run build 完整重建。