docs: 重写 README，新增宝塔面板部署指南
1 个文件变更
+430
-53
fangqihang1717@163.com
| •README.md | +430 -53 |
变更内容
diff --git a/README.md b/README.md
index 925ff3f..e01bc25 100644
--- a/README.md
+++ b/README.md
@@ -1,77 +1,454 @@
+<div align="center">
+
# ClearLove 表白墙 2.0
-基于 Go 1.27 的单二进制表白墙 Web 应用，包含 **安装向导 / 前台 / 后台管理** 三大模块，
-兼容 **SQLite（默认）与 MySQL**，完美适配 PC 与移动端，全部资源内嵌，无任何国外 CDN 依赖。
+**用 Go 构建你的专属表白墙 —— 单二进制、双数据库、插件生态**
+
+安装向导 · 瀑布流前台 · 可视化后台 · 云端插件市场
+
+[](https://go.dev)
+[](https://git.kazx.top/fqh/Clearlove2.0/releases)
+[](LICENSE)
+[](#)
+[](#)
+[](#)
+
+[功能特性](#-功能特性) · [快速开始](#-快速开始) · [宝塔面板部署](#-宝塔面板部署推荐) · [Docker 部署](#-docker-部署) · [配置项](#-配置项) · [目录结构](#-目录结构) · [插件生态](#-插件生态) · [常见问题](#-常见问题)
+
+</div>
+
+---
+
+## 📖 简介
+
+ClearLove 表白墙是一套面向个人与小型社区的**表白墙 / 匿名留言墙**系统，使用 Go 编写，编译后是**一个可执行文件**：模板、样式、脚本全部使用 `embed` 内嵌，运行时不需要额外安装任何运行时或依赖。
+
+- 🧳 **单文件部署** —— 上传即跑，无需 Docker、PHP、Node.js
+- 🗄️ **双数据库兼容** —— 默认 SQLite 零配置，也可切换 MySQL
+- 🧩 **插件生态** —— 钩子式插件 + 云端插件市场，后台一键安装
+- 🤖 **AI 内容审核** —— 兼容 OpenAI 格式，支持发帖预审与定时巡查
+- 📱 **移动端适配** —— 前台瀑布流与后台管理均适配 PC / 手机
+- 🔒 **安全默认** —— bcrypt、HMAC 会话、CSRF、XSS 转义、IP/指纹封禁
+
+> 云端插件社区（独立模块 [`cloud/`](cloud/)）同时提供官网、插件市场、开发者发布与开放 API，部署于 <https://clearlove.kazx.top>。
+
+---
+
+## ✨ 功能特性
+
+### 前台
+
+| 模块 | 说明 |
+|---|---|
+| 瀑布流首页 | 无限滚动 + 图片懒加载，话题筛选，卡片展示最新 4 条评论 |
+| 发帖 | ≤3000 字，图片 ≤15 张（自动转 WebP，单张 ≤10MB），视频 ≤3 个（单个 ≤70MB），上传进度条，话题选择或新建 |
+| 发帖验证 | 点击发布后弹出 4 位数字图形验证码（SVG，一次性消费），上传区支持拖拽与点击 |
+| 互动 | 点赞（按浏览器指纹去重，支持匿名）、评论、举报 |
+| 账号 | 注册 / 登录（可配置邮箱验证码），个人主页可编辑、删除自己的帖子 |
+| 展示 | 公告每日一次提示、社区守则、主题背景图、捐赠二维码 |
+
+### 后台（`/admin`）
+
+| 模块 | 说明 |
+|---|---|
+| 仪表盘 | 用户数、帖子数、今日新增、近 7 天活跃、待处理举报 |
+| 帖子管理 | 编辑、删除、按 IP 或浏览器指纹封禁发帖者 |
+| 举报管理 | 人工处理（保留 / 隐藏 / 删除），AI 每 10 分钟自动巡查并留痕 |
+| 用户 / 管理员 | 用户启用禁用；管理员支持 `super` 与自定义权限组（8 个权限粒度） |
+| 网站设置 | 站名、主题与背景、注册与发帖开关、SMTP、AI 接入、插件商店云端地址 |
+| 内容运营 | 公告、话题、社区守则 |
+| 插件 | zip 上传安装、启用 / 禁用 / 卸载，**插件商店一键安装云端插件** |
+| 开放能力 | API Key 管理 + `/api/v1/*` RESTful 接口 |
+| 其他 | 关于、检查更新、捐赠开发者 |
+
+### 技术与安全
+
+- **单二进制**：`CGO_ENABLED=0` 静态编译，Linux amd64 / arm64 可直接运行
+- **双数据库**：SQLite（`modernc.org/sqlite`，纯 Go 无 CGO）与 MySQL 行为一致，建表迁移幂等
+- **图片处理**：上传图片自动等比压缩（最长边 1600）并转 WebP
+- **AI 审核**：发帖预审拦截 + 定时自动巡查，动作写日志留痕
+- **安全**：bcrypt 密码、HMAC 签名 Cookie 会话、CSRF 双提交校验、XSS 标签剥离、全参数化 SQL、IP/指纹封禁
+
+---
+
+## 🚀 快速开始
+
+### 方式一：下载二进制（推荐）
-## 快速开始
+从 [Releases](https://git.kazx.top/fqh/Clearlove2.0/releases) 或发布包中获取对应架构的文件：
+
+| 文件 | 适用环境 |
+|---|---|
+| `clearlove-linux-amd64` | x86_64 云服务器 / VPS |
+| `clearlove-linux-arm64` | ARM 云主机 / 树莓派 |
```bash
-# 1. 拉取依赖并编译
-go mod tidy
-go build -o clearlove.exe .
+chmod +x clearlove-linux-amd64
+mv clearlove-linux-amd64 clearlove
+./clearlove
+```
-# 2. 运行（默认 16868 端口，可用环境变量 PORT 修改）
-./clearlove.exe
+启动后访问 `http://服务器IP:16868/install` 完成安装向导。
+
+### 方式二：从源码编译
+
+```bash
+git clone https://git.kazx.top/fqh/Clearlove2.0.git
+cd Clearlove2.0
+
+go mod tidy
+go build -o clearlove . # Windows 可加 .exe 后缀
+./clearlove
```
-### 交叉编译 Linux 版本（在 Windows 上直接出包）
+<details>
+<summary><b>交叉编译 Linux 版本（Windows 上直接出包）</b></summary>
```bash
-# x86_64 服务器
+# x86_64
set CGO_ENABLED=0 && set GOOS=linux && set GOARCH=amd64 && go build -trimpath -ldflags "-s -w" -o clearlove .
# ARM64（树莓派 / ARM 云主机）
set CGO_ENABLED=0 && set GOOS=linux && set GOARCH=arm64 && go build -trimpath -ldflags "-s -w" -o clearlove .
-# Linux/macOS 下等价写法
+# Linux / macOS 下等价写法
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags "-s -w" -o clearlove .
```
-发布包（含 systemd 单元、Nginx 示例、部署说明）见 `dist/` 目录。
+</details>
+
+### 安装向导（三步）
+
+首次启动访问 `http://IP:16868/install`：
+
+1. **选择数据库** —— SQLite（默认，零配置）或 MySQL（填写主机 / 端口 / 库名 / 账号密码，安装时自动建表）
+2. **填写网站名称**
+3. **设置管理员账号** —— 完成后进入后台 `/admin`
+
+安装状态与数据库配置保存在 `data/config.json`，之后启动直接进入前台首页。
-首次启动访问 `http://localhost:16868/install` 完成三步安装向导：
+---
-1. 选择数据库（SQLite 默认 / MySQL 需填连接信息，安装时自动建表）
-2. 填写网站名称
-3. 设置管理员账号（后台入口 `/admin`）
+## 🧭 宝塔面板部署（推荐）
-安装完成后配置保存在 `data/config.json`，后续启动直接进入前台首页。
+> 适用于宝塔 Linux 面板（7.9+ / 9.x）。核心思路：**二进制 + 进程守护 + 反向代理**，
+> 让程序常驻在 `127.0.0.1:16868`，由 Nginx 对外提供 80/443 访问。
-## 目录说明
+### 0. 环境准备
-| 路径 | 说明 |
+| 项目 | 要求 |
|---|---|
-| `main.go` | 入口与路由注册 |
-| `internal/config` | 配置与安装状态持久化 |
-| `internal/database` | 双数据库连接与迁移 |
-| `internal/models` | 数据模型与设置缓存 |
-| `internal/util` | 会话/验证码/WebP/上传/日志工具 |
-| `internal/middleware` | 安全头、安装门禁、CSRF、封禁 |
-| `internal/mailer` | SMTP 邮件（465 SSL / 587 STARTTLS） |
-| `internal/ai` | OpenAI 格式接入、发帖预审、每10分钟自动巡查 |
-| `internal/plugin` | 钩子式插件系统 |
-| `internal/handlers` | 安装/前台/认证/后台/API 处理器 |
-| `web/templates` | 全部页面模板（内嵌） |
-| `web/static` | CSS/JS/默认主题（内嵌） |
-| `data/` | 运行时：config.json、SQLite、主题、插件 |
-| `uploads/` | 运行时：图片（自动转 webp）与视频 |
-
-## 功能清单
-
-**前台**：瀑布流无限滚动、图片懒加载、帖子卡片（昵称/内容/图片/视频/点赞/评论/最新4条评论折叠）、
-发帖（≤3000字、≤15图自动 webp、≤3视频单个≤70MB、上传进度条、话题选择/新建、4位数字验证码）、
-登录注册（可选邮箱验证码）、个人主页（编辑/删除自己的帖子）、举报。
-
-**后台（/admin）**：仪表盘统计、帖子管理（编辑/删除/IP与浏览器指纹封禁）、网站设置（站名/主题/登录开关/SMTP/AI接入）、
-举报管理（AI 每10分钟自动巡查执行保留/隐藏/删除并留痕、发帖自动审核）、用户管理、管理员管理（角色与权限组）、
-公告与话题与社区守则、插件管理（zip 上传/启用/禁用/卸载）、API 接口（API Key + RESTful 全覆盖）、关于、检查更新、捐赠开发者。
-
-## 文档
-
-- 主题开发：[docs/THEME.md](docs/THEME.md)
-- 插件开发：[docs/PLUGIN.md](docs/PLUGIN.md)
-
-## 安全
-
-bcrypt 密码存储、HMAC 签名 Cookie、CSRF 双提交校验、XSS 转义与标签剥离、
-全参数化 SQL、上传体积与类型校验、IP/指纹封禁、统一错误日志。
+| 服务器 | Linux（CentOS 7+ / Ubuntu 20.04+ / Debian 11+），1 核 1G 起 |
+| 面板 | 已安装宝塔 Linux 面板，并已安装 **Nginx** |
+| 文件 | `clearlove-linux-amd64`（或 arm64），无需安装 Go 环境 |
+
+### 1. 上传二进制并试运行
+
+1. 面板左侧「**文件**」→ 进入 `/www/wwwroot/` → 新建目录 `clearlove`
+2. 上传 `clearlove-linux-amd64`，重命名为 `clearlove`
+3. 右键该文件 →「**权限**」→ 设为 `755`（或勾选"所有用户可执行"）
+4. 打开面板左侧「**终端**」，执行：
+
+```bash
+cd /www/wwwroot/clearlove
+chmod +x clearlove
+./clearlove
+```
+
+看到类似输出即表示正常（此时会创建 `data/` 与 `uploads/` 目录）：
+
+```
+ClearLove 表白墙 2.0 | 数据目录: data | 上传目录: uploads
+检测到未安装，请访问 http://localhost:16868/install 完成安装向导
+```
+
+按 `Ctrl + C` 退出，接下来交给守护进程常驻运行。
+
+### 2. 用「进程守护管理器」让程序常驻
+
+1. 面板左侧「**软件商店**」→「官方应用」→ 搜索 **进程守护管理器**（Supervisor）→ 安装
+2. 打开插件 →「**添加守护进程**」，按下表填写：
+
+| 字段 | 填写内容 |
+|---|---|
+| 名称 | `clearlove`（**不要使用中文**） |
+| 启动用户 | `www` |
+| 运行目录 | `/www/wwwroot/clearlove` |
+| 启动命令 | `/www/wwwroot/clearlove/clearlove` |
+
+> 💡 若提示「文件不可执行」或进程反复重启，通常是权限问题，先执行：
+> ```bash
+> chown -R www:www /www/wwwroot/clearlove
+> chmod +x /www/wwwroot/clearlove/clearlove
+> ```
+> 进程日志可在插件界面查看，文件位于 `/www/server/panel/plugin/supervisor/log`。
+
+### 3. 添加站点 + 反向代理
+
+1. 面板左侧「**网站**」→「**添加站点**」：
+ - 域名：你的域名，如 `wall.example.com`
+ - 数据库 / PHP 版本：**都不需要**（数据库在安装向导里配置）
+2. 点击刚创建的站点 → 顶部「**域名**」→ 左侧「**反向代理**」→「**添加反向代理**」：
+
+| 字段 | 填写内容 |
+|---|---|
+| 代理名称 | `clearlove` |
+| 目标 URL | `http://127.0.0.1:16868` |
+| 发送域名 | `$host` |
+| 代理目录 | 留空（表示代理全站） |
+| 内容替换 | 留空（仅 Nginx 支持，最多 3 条） |
+
+> ⚠️ 官方文档提示：目标 URL 必须是可正常访问的地址，否则会返回错误；设置反向代理后，站点「访问限制」中的对应路径规则会失效。
+
+3. 保存后直接访问域名，应能看到安装向导（未安装时自动跳转 `/install`）。
+
+### 4. 申请 HTTPS 证书
+
+站点 →「**SSL**」→「**Let's Encrypt**」→ 勾选域名 → 申请；
+签发成功后建议开启「**强制 HTTPS**」。程序会自动识别 Nginx 传递的 `X-Forwarded-For` / `X-Real-IP`，封禁与统计拿到的是真实访客 IP。
+
+### 5. 完成安装向导
+
+浏览器访问 `https://你的域名/install`：
+
+- **SQLite**：直接下一步（数据文件位于 `/www/wwwroot/clearlove/data/clearlove.db`）
+- **MySQL**：先在面板「**数据库**」中新建一个库（如 `clearlove`，字符集 `utf8mb4`），然后在向导中填写
+ `主机 127.0.0.1`、`端口 3306`、库名、用户名、密码
+
+最后填写网站名称与管理员账号，完成安装。
+
+### 6. 上传大文件的调整
+
+前台允许上传单个 ≤70MB 的视频。若上传报 413 / 失败，请调大 Nginx 请求体上限：
+
+站点 →「**配置文件**」，在 `server { ... }` 中加入并保存（宝塔会自动重载 Nginx）：
+
+```nginx
+client_max_body_size 100m;
+```
+
+### 7. 备份与升级
+
+- **备份**：面板「计划任务」→ 添加「备份目录」，分别备份
+ `/www/wwwroot/clearlove/data` 与 `/www/wwwroot/clearlove/uploads`（或使用 MySQL 备份任务）
+- **升级**：上传新的二进制覆盖 `clearlove` → 进程守护管理器里「**重启**」该进程即可，`data/` 与 `uploads/` 保持不动
+
+### 宝塔部署常见问题
+
+| 现象 | 排查方向 |
+|---|---|
+| 访问域名 502 Bad Gateway | 守护进程未运行或报错：查看 Supervisor 日志；确认 `./clearlove` 能手动跑起来 |
+| 提示文件不可执行 | `chmod +x clearlove`，并确认启动用户 `www` 有读取 / 执行权限 |
+| 安装向导无法写入数据库 | 目录权限：`chown -R www:www /www/wwwroot/clearlove`，确认 `data/` 可写 |
+| 上传视频失败 | 调大 `client_max_body_size`；确认磁盘剩余空间充足 |
+| 后台看到所有 IP 都是 127.0.0.1 | 确认使用宝塔「反向代理」而非其他转发方式，程序读取 `X-Forwarded-For` 取真实 IP |
+| 端口 16868 想改成别的 | 在守护进程「启动命令」前加环境变量：`PORT=8080 /www/wwwroot/clearlove/clearlove`，同时改反向代理目标端口 |
+
+<details>
+<summary><b>可选：用 systemd 代替进程守护管理器</b></summary>
+
+不使用宝塔进程守护插件时，也可以直接写 systemd 单元（`/etc/systemd/system/clearlove.service`）：
+
+```ini
+[Unit]
+Description=ClearLove 表白墙
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=/www/wwwroot/clearlove
+ExecStart=/www/wwwroot/clearlove/clearlove
+Environment=PORT=16868
+Environment=CLEARLOVE_DATA_DIR=/www/wwwroot/clearlove/data
+Environment=CLEARLOVE_UPLOAD_DIR=/www/wwwroot/clearlove/uploads
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+systemctl daemon-reload
+systemctl enable --now clearlove
+systemctl status clearlove
+```
+
+</details>
+
+---
+
+## 🐳 Docker 部署
+
+二进制为 `CGO_ENABLED=0` 静态编译，可直接在 `alpine` 等最小镜像中运行，无需自己写 Dockerfile：
+
+```bash
+mkdir -p /www/wwwroot/clearlove && cd /www/wwwroot/clearlove
+# 上传 clearlove 二进制并 chmod +x
+
+docker run -d --name clearlove --restart=always \
+ -p 16868:16868 \
+ -v /www/wwwroot/clearlove:/app \
+ -w /app \
+ alpine:3.20 ./clearlove
+```
+
+在宝塔中使用图形界面时：**Docker → 网站 → 运行环境 → Go → 创建**（官方文档流程：上传项目文件 → 在运行环境中创建 → 创建网站 → 访问测试）。
+
+---
+
+## ⚙️ 配置项
+
+程序通过环境变量读取运行参数，均可在启动前设置：
+
+| 环境变量 | 说明 | 默认值 |
+|---|---|---|
+| `PORT` | 监听端口（优先级最高） | `16868` |
+| `CLEARLOVE_PORT` | 监听端口（次优先） | `16868` |
+| `CLEARLOVE_DATA_DIR` | 数据目录：config.json、SQLite、主题、插件 | `./data` |
+| `CLEARLOVE_UPLOAD_DIR` | 上传目录：图片与视频 | `./uploads` |
+
+> 数据库连接、站点名称等运行期配置保存在 `data/config.json` 与数据库 `settings` 表中，
+> 安装向导完成后无需再手工编辑。
+
+---
+
+## 📁 目录结构
+
+```
+.
+├── main.go # 入口与路由注册
+├── internal/
+│ ├── config/ # 配置与安装状态持久化
+│ ├── database/ # SQLite / MySQL 连接与自动迁移
+│ ├── models/ # 数据模型、设置缓存、权限组
+│ ├── util/ # 会话、验证码、WebP、上传、日志
+│ ├── middleware/ # 安全头、安装门禁、CSRF、封禁
+│ ├── mailer/ # SMTP 邮件（465 SSL / 587 STARTTLS）
+│ ├── ai/ # OpenAI 兼容接入、预审、自动巡查
+│ ├── plugin/ # 钩子式插件系统
+│ └── handlers/ # 安装 / 前台 / 认证 / 后台 / API / 插件商店
+├── web/
+│ ├── templates/ # 全部页面模板（内嵌）
+│ └── static/ # CSS / JS / 默认主题（内嵌）
+├── docs/
+│ ├── THEME.md # 主题开发文档
+│ └── PLUGIN.md # 插件开发文档
+└── cloud/ # 云端插件社区（独立 Go 模块，SQLite）
+ ├── main.go
+ ├── internal/ # 配置 / 数据库 / 模型 / 中间件 / 处理器
+ ├── web/ # 官网、插件市场、开发者后台、管理后台
+ └── deploy/ # systemd 单元与 Nginx 示例
+```
+
+运行时生成（**不在版本库中，升级时请勿删除**）：
+
+| 目录 | 内容 |
+|---|---|
+| `data/` | `config.json`、SQLite 数据库、主题、插件 |
+| `uploads/` | 图片（自动转 WebP）与视频，按日期分子目录 |
+
+---
+
+## 🧩 插件生态
+
+### 为站点安装插件
+
+后台「**插件管理 → 插件商店**」，云端地址默认 `https://clearlove.kazx.top`（可在「网站设置」中修改）。
+
+安装流程：拉取市场列表 → 下载 zip → **SHA256 完整性校验** → 落盘 → 回到插件管理页「**启用**」。
+
+### 开发并发布插件
+
+插件就是一个包含 `plugin.json` 的 zip 包：
+
+```json
+{
+ "name": "每日一言",
+ "version": "1.0.0",
+ "author": "yourname",
+ "description": "在页面底部展示一句随机语录",
+ "hooks": [
+ { "hook": "footer_html", "type": "html", "html": "<div class=\"quote\">今天也要加油鸭</div>" },
+ { "hook": "content_filter", "type": "filter", "match": "广告|加群", "replace": "***" },
+ { "hook": "post_created", "type": "http", "url": "https://example.com/webhook" }
+ ]
+}
+```
+
+| 钩子类型 | 钩子名 | 用途 |
+|---|---|---|
+| `html` | `header_html` / `footer_html` | 向页面头部 / 底部注入 HTML |
+| `filter` | `content_filter` | 正则改写帖子与评论内容 |
+| `http` | `post_created` / `comment_created` / `report_created` | 事件 Webhook（POST JSON，带 `X-ClearLove-Event` 头） |
+
+发布流程：在云端 <https://clearlove.kazx.top/dev/register> 注册开发者（邮箱验证）→ 开发者后台上传 zip → 管理员审核上架 → 所有站点即可一键安装。详见 [docs/PLUGIN.md](docs/PLUGIN.md)。
+
+---
+
+## ❓ 常见问题
+
+<details>
+<summary><b>一定要用 Nginx / 宝塔吗？</b></summary>
+
+不需要。程序自带 HTTP 服务，直接 `./clearlove` 就能用 `http://IP:16868` 访问。反向代理只是为了得到 80/443 端口与 HTTPS 证书。
+</details>
+
+<details>
+<summary><b>SQLite 和 MySQL 怎么选？</b></summary>
+
+个人站或日活不高的社区用默认 SQLite 即可，零配置、备份就是复制 `data/` 目录；已有 MySQL 或需要多实例共享数据时再选 MySQL。
+</details>
+
+<details>
+<summary><b>升级会丢数据吗？</b></summary>
+
+不会。替换二进制后重启即可，程序启动时会自动执行幂等的建表 / 索引迁移，`data/` 与 `uploads/` 目录保持不变。
+</details>
+
+<details>
+<summary><b>忘记后台管理员密码怎么办？</b></summary>
+
+删除 `data/config.json`（不含数据库文件本身），然后重新访问 `/install`，在向导中**选择与原来完全相同的数据库配置**，即可新建一个管理员账号 —— 建表迁移是幂等的，原有帖子、用户与设置都不会丢失。
+
+> ⚠️ 向导中若改选了另一种数据库或另一个库，程序会连到新的库，请务必与首次安装时保持一致。
+</details>
+
+<details>
+<summary><b>AI 审核是必须的吗？</b></summary>
+
+不是。默认关闭，需在后台「网站设置 → AI 模型接入」中填写兼容 OpenAI 的服务地址、密钥与模型名后才会生效。
+</details>
+
+---
+
+## 📚 文档
+
+- [主题开发](docs/THEME.md) —— 目录结构与 CSS 变量
+- [插件开发](docs/PLUGIN.md) —— 钩子规范与打包要求
+- 云端服务部署：见 [`cloud/deploy/`](cloud/deploy/) 中的 systemd 单元与 Nginx 示例
+
+---
+
+## 🔐 安全
+
+- 密码使用 **bcrypt** 存储，会话为 **HMAC 签名 Cookie**（无状态，用户 30 天 / 管理员 12 小时）
+- 所有写操作校验 **CSRF 双提交令牌**（API Key 调用除外）
+- 用户输入统一剥离 HTML 标签，模板输出自动转义
+- 数据库访问全部使用**参数化 SQL**
+- 上传做扩展名、体积与数量校验；图片经解码重编码为 WebP
+- 支持按 **IP / 浏览器指纹** 封禁，AI 与管理员操作全程留痕
+
+> 如发现安全问题，请通过仓库 Issue 私下联系维护者，感谢你的负责披露。
+
+---
+
+## 📄 许可
+
+本项目基于 [MIT License](LICENSE) 开源。
+
+<div align="center">
+
+**如果这个项目对你有帮助，欢迎点一个 ⭐ Star**
+
+</div>