Web Panel

Web Panel

事实来源：主仓 pr-88 @ a312645 的 panel/（React + TypeScript + SCSS Modules + Framer Motion）、src/souwen/server/routes/panel.py，以及主仓 docs/appearance.md。

SouWen 自带一个单进程 Web 面板，集成在 FastAPI 中。访问 http://<host>:<port>/panel#/（HashRouter）。本页讲怎么用 + 怎么换皮肤 + 排障。

---

1. 入口

URL	用途
/panel#/	浏览器入口（HashRouter，# 是前端路由）
/panel	静态 HTML（被 /panel#/ 自动调用）
/api/v1/whoami	Panel 启动时调，决定显示哪些菜单

不要写成 /panel/#/——前后是不同 URL。

---

2. 4 个皮肤

皮肤	风格	默认？
souwen-google	鲜艳 Google 风（默认）	✓
souwen-nebula	深空星云	—
carbon	终端风（IBM Carbon 启发）	—
apple	Apple HIG	—
ios	iOS / macOS Settings	—

souwen-google / souwen-nebula 还含 /plugins 路由；carbon / apple / ios 至少含 9 个标准 NAV_ITEMS。

切换皮肤

• 构建时：docker build --build-arg SKINS=souwen-google 单皮肤减小体积。
• 运行时：docker run -e VITE_SKINS=...（HF Space / ModelScope 默认）。
• 多皮肤：默认 SKINS=all，登录后浏览器选择。

---

3. 9 个 NAV_ITEMS

按 whoami features 决定可见性：

路径	Feature	角色	用途
/dashboard	—	任何已登录角色	概览（健康度 / 出口 IP / 限流）
/search	search	User+	搜索 UI
/fetch	fetch	Admin（fetch 高 SSRF 风险）	抓取 UI
/video	search	User+	YouTube + Bilibili 操作
/tools	search / wayback_save	User / Admin	links / sitemap / wayback
/sources	sources_config_read	User+	数据源状态
/network	proxy_admin	Admin	代理 / HTTP backend
/warp	warp_admin	Admin	WARP 启停 / 注册 / 测试 / 组件
/config	config_read	User+	配置查看 / 写入
/plugins	—	Admin	插件管理（部分皮肤）

User 看不到 /network /warp /plugins /config 写入 / /fetch。

---

4. ETag 缓存

/panel HTML 走内存缓存：

ETag: "<sha256-16hex>"
Cache-Control: public, max-age=3600

客户端 If-None-Match 命中返 304（仅头部，无 body）。支持 RFC 7232 通配符 * 与逗号分隔列表。Nginx / Caddy 等反代默认会透传 ETag。

---

5. 登录

启动后第一次访问会要求 Bearer Token：

• User Token：用 user_password / visitor_password / api_password
• Admin Token：用 admin_password / api_password

详见 Authentication and Roles。

Guest 模式（guest_enabled=true） 进 Panel 后只看到 /search 简化版。

---

6. 自定义皮肤

panel/src/skins/ 加新目录：

panel/src/skins/my-skin/
├── components/
├── pages/
├── styles/                    # html[data-skin='my-skin'] 命名空间
├── stores/
├── routes.tsx
├── skin.config.ts             # 元信息 + 配色
└── index.ts                   # 导出 SkinModule (含 bootstrap, ErrorBoundary, Spinner)

约束：

• 用 @core/... 引用共享模块；皮肤间不互相 import。
• 动画用 Framer Motion 的 m（不是 motion）；type: 'spring' 加 as const。
• 不用 Tailwind——项目用 SCSS Modules + CSS Variables。
• 在 vite.config.ts 的 ALL_SKINS 注册。

构建：

cd panel
VITE_SKINS=my-skin npm run build

详见主仓 docs/contributing.md#前端开发 与 docs/appearance.md。

---

7. 排障

现象	修复
登录后空白	浏览器 DevTools → Network 看 /api/v1/whoami 是否 200；可能 Token 过期或反代出错
看不到某菜单	角色不够；/api/v1/whoami 看 features.<feature>
/panel 静态资源 404	反代没把 /panel 路径映射对（看 Deployment Guide Nginx 模板）
切换皮肤无效	构建时 VITE_SKINS 是否含目标皮肤；浏览器是否清缓存
WarpPage 看不到组件按钮	SOUWEN_ADMIN_OPEN=1 / Admin 鉴权是否就绪
/plugins 看不到	当前皮肤可能未注册 plugins 路由（仅 souwen-google / souwen-nebula 有）

---

8. 接下来

• Authentication and Roles — 角色 → 菜单可见性
• Plugins · Network and WARP — Panel 后台对应的运维操作
• Deployment Guide — 反向代理静态资源
• 主仓 docs/appearance.md