From d29d388092abe7932b08216c6fa2cb155577c38e Mon Sep 17 00:00:00 2001
From: Victor_Jay <ovoex.cn@gmail.com>
Date: Wed, 27 May 2026 15:52:56 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E7=AB=99=E7=82=B9?=
 =?UTF-8?q?=E8=AE=BE=E7=BD=AE=E7=AE=A1=E7=90=86=E6=96=87=E6=A1=A3=EF=BC=8C?=
 =?UTF-8?q?=E7=A7=BB=E9=99=A4=20JS=20=E6=AD=BB=E4=BB=A3=E7=A0=81=EF=BC=8C?=
 =?UTF-8?q?=E5=90=8C=E6=AD=A5=20config.yaml=20=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 docs/site-settings.md：站点设置全量文档（可配置项/架构/权限/API）
- config.yaml 补充 site.* / registration.* 运行时配置说明
- site-settings.js 移除已废弃的 site.brand 过滤项
---
 config.yaml                                |  6 ++-
 docs/site-settings.md                      | 63 ++++++++++++++++++++++
 templates/admin/static/js/site-settings.js |  2 +-
 3 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 docs/site-settings.md

diff --git a/config.yaml b/config.yaml
index eebd386..517013f 100644
--- a/config.yaml
+++ b/config.yaml
@@ -22,7 +22,11 @@ jwt:
 bcrypt:
   cost: 12
 
-# 审核系统配置（站点设置可运行时覆盖，无需重启）
+# 站点设置（运行时通过管理后台 /admin/site-settings 配置，DB持久化+内存缓存，无需重启）
+# site.framework      页脚附加标识，默认 "Framework: MetaZone"，留空则隐藏
+# site.copyright_start 版权起始年，默认 "2024"
+# registration.enabled 是否允许新用户注册，默认 true
+# audit.*              审核系统配置，可运行时覆盖本文件默认值
 audit:
   enabled: true                 # 审核总开关
   username_audit: true          # 用户名修改审核
diff --git a/docs/site-settings.md b/docs/site-settings.md
new file mode 100644
index 0000000..0bfb686
--- /dev/null
+++ b/docs/site-settings.md
@@ -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 | 获取单个布尔值 |
diff --git a/templates/admin/static/js/site-settings.js b/templates/admin/static/js/site-settings.js
index 7d87174..1dd13b9 100644
--- a/templates/admin/static/js/site-settings.js
+++ b/templates/admin/static/js/site-settings.js
@@ -16,7 +16,7 @@
 
     // 已有专属 UI 的设置 key，不在"其他设置"中重复显示
     var DEDICATED_KEYS = {
-        'site.brand': true, 'site.framework': true, 'site.copyright_start': true,
+        'site.framework': true, 'site.copyright_start': true,
         'registration.enabled': true,
         'audit.enabled': true, 'audit.username_audit': true, 'audit.avatar_audit': true, 'audit.bio_audit': true
     };