docs: 新增站点设置管理文档,移除 JS 死代码,同步 config.yaml 注释

- 新增 docs/site-settings.md:站点设置全量文档(可配置项/架构/权限/API)
- config.yaml 补充 site.* / registration.* 运行时配置说明
- site-settings.js 移除已废弃的 site.brand 过滤项
This commit is contained in:
2026-05-27 15:52:56 +08:00
parent dfbd93c847
commit d29d388092
3 changed files with 69 additions and 2 deletions

63
docs/site-settings.md Normal file
View File

@ -0,0 +1,63 @@
# 管理后台 — 站点设置
## 概述
站点设置位于管理后台 `/admin/site-settings`,仅 **owner站长** 可访问。
设置通过 DB`site_settings` 表)持久化 + 内存缓存,运行时修改即时生效,无需重启。
## 可配置项
### 基本设置
| Key | 类型 | 默认值 | 说明 |
|-----|------|--------|------|
| `site.framework` | string | `Framework: MetaZone` | 页脚附加标识,留空则隐藏 |
| `site.copyright_start` | string | `2024` | 版权起始年,页脚渲染 `© 起始年-当前年` |
### 注册设置
| Key | 类型 | 默认值 | 说明 |
|-----|------|--------|------|
| `registration.enabled` | bool | `true` | 关闭后新用户无法注册API 返回 403 |
### 审核设置
| Key | 类型 | 默认值 | 说明 |
|-----|------|--------|------|
| `audit.enabled` | bool | `true` | 审核总开关 |
| `audit.username_audit` | bool | `true` | 用户名修改需审核 |
| `audit.avatar_audit` | bool | `true` | 头像修改需审核 |
| `audit.bio_audit` | bool | `true` | 签名修改需审核 |
## 工作原理
### 存储架构
```
config.yaml (默认值) → DB site_settings 表 → 内存缓存 → 运行时读取
```
1. 启动时从 DB 全量加载到内存(`config.SiteSettings`
2. 写入先落 DB再更新内存`Set()` / `SetBool()`
3. 读取纯内存,不查 DB`RLock`
4. 不存在于 DB 的 key 自动 fallback `config.yaml` 默认值
### 模板注入
全局中间件 `InjectSiteInfo` 读取 `Framework` / `CopyrightStart`,注入 `gin.Context`
`BuildPageData` 从 context 提取后注入所有 SSR 模板,无需逐个 Controller 修改。
### 页脚管理入口
页脚末尾自动追加“管理面板”链接,**moderator 及以上角色**可见。
## API 路由
| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/admin/site-settings` | owner | 获取所有设置 + 审核设置 |
| PUT | `/api/admin/site-settings` | owner | 更新单项字符串设置 |
| PUT | `/api/admin/site-settings/bool` | owner | 更新单项布尔设置 |
| GET | `/api/admin/site-settings/bool?key=...` | owner | 获取单个布尔值 |