ClearLove 表白墙 2.0

用 Go 构建你的专属表白墙 —— 单二进制、双数据库、插件生态

安装向导 · 瀑布流前台 · 可视化后台 · 云端插件市场

功能特性 · 快速开始 · 宝塔面板部署 · Docker 部署 · 配置项 · 目录结构 · 插件生态 · 常见问题

---

📖 简介

ClearLove 表白墙是一套面向个人与小型社区的表白墙 / 匿名留言墙系统，使用 Go 编写，编译后是一个可执行文件：模板、样式、脚本全部使用 embed 内嵌，运行时不需要额外安装任何运行时或依赖。

• 🧳 单文件部署 —— 上传即跑，无需 Docker、PHP、Node.js
• 🗄️ 双数据库兼容 —— 默认 SQLite 零配置，也可切换 MySQL
• 🧩 插件生态 —— 钩子式插件 + 云端插件市场，后台一键安装
• 🤖 AI 内容审核 —— 兼容 OpenAI 格式，支持发帖预审与定时巡查
• 📱 移动端适配 —— 前台瀑布流与后台管理均适配 PC / 手机
• 🔒 安全默认 —— bcrypt、HMAC 会话、CSRF、XSS 转义、IP/指纹封禁

官方插件社区部署于 https://clearlove.kazx.top，提供插件市场、开发者发布与开放 API，表白墙后台可一键安装其中的插件。

---

✨ 功能特性

前台

模块	说明
瀑布流首页	无限滚动 + 图片懒加载，话题筛选，卡片展示最新 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 或发布包中获取对应架构的文件：

文件	适用环境
clearlove-linux-amd64	x86_64 云服务器 / VPS
clearlove-linux-arm64	ARM 云主机 / 树莓派

chmod +x clearlove-linux-amd64
mv clearlove-linux-amd64 clearlove
./clearlove

启动后访问 http://服务器IP:16868/install 完成安装向导。

方式二：从源码编译

git clone https://git.kazx.top/fqh/Clearlove2.0.git
cd Clearlove2.0

go mod tidy
go build -o clearlove .          # Windows 可加 .exe 后缀
./clearlove

# 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 下等价写法
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags "-s -w" -o clearlove .

安装向导（三步）

首次启动访问 http://IP:16868/install：

1. 选择数据库 —— SQLite（默认，零配置）或 MySQL（填写主机 / 端口 / 库名 / 账号密码，安装时自动建表）
2. 填写网站名称
3. 设置管理员账号 —— 完成后进入后台 /admin

安装状态与数据库配置保存在 data/config.json，之后启动直接进入前台首页。

从 PHP 旧版（1.x）迁移数据

如果原来用的是 ClearLove PHP 版（clearlove-lovecards 1.x），可以把老站数据整体搬到 2.0。 先完成新版安装（能正常打开首页），然后二选一：

方式一：后台上传迁移（推荐）

后台左侧「数据迁移」→ 上传旧版数据库文件 → 勾选「试运行」先看数量 → 确认无误后取消勾选再执行一次。

支持的文件	获取方式
旧版 SQLite 的 data.db	旧版项目根目录下的同名文件
旧版 MySQL 导出的 .sql	宝塔「数据库 → 备份」下载，或 mysqldump -u用户 -p 库名 > old.sql

上传后程序会自动识别类型，无需手动选择。「旧版 uploads 目录」填写服务器上的绝对路径（如 /www/wwwroot/old/uploads）时，会把旧站图片与视频复制到新版 uploads/legacy/；留空则只迁移文字数据。迁移在后台异步执行，可以关掉页面，稍后回来查看结果。

方式二：命令行

# 先试运行（只统计、不写入），确认数量后再正式执行
./clearlove migrate /www/wwwroot/old/data.db -uploads /www/wwwroot/old/uploads -dry
./clearlove migrate /www/wwwroot/old/data.db -uploads /www/wwwroot/old/uploads

# MySQL 导出文件同样支持（自动识别）
./clearlove migrate /www/wwwroot/old/old.sql

迁移内容	说明
帖子 / 评论 / 话题	保留原始 ID 与时间；旧版状态语义（0 正常 / 1 隐藏）自动取反为新版（1 可见 / 0 隐藏）
图片与视频	从旧版 uploads/ 复制到新版 uploads/legacy/，文件缺失会跳过并统计
点赞数	保留计数，并按其数量补齐占位记录，避免迁移后被一次点赞清零
公告	仅迁移启用中的公告，正文前 20 字作为新版标题
用户 / 管理员	密码同为 bcrypt（PHP $2y$ 与 Go 兼容），可直接用原密码登录
封禁名单	ip / fingerprint 原样迁移
举报记录	状态归一为新版的「待处理 / 已处理」

❌ 不迁移：访问量统计（新版统计口径不同）、帖子置顶（新版无此功能）、旧版主题与界面配置（需在新后台重新设置）。 ✅ 迁移可重复执行，已存在的记录会按 ID / 用户名 / 封禁项自动跳过；-uploads 省略时默认取旧库同级的 uploads/ 目录。

---

🧭 宝塔面板部署（推荐）

新版宝塔面板在「网站 → Go项目」中内置了 Go 项目部署能力（正式版 7.9.3+ 起）： 选择编译好的二进制、填好端口即可运行，面板自带守护进程（约 120 秒检测一次）， 无需在服务器安装 Go 环境，也不需要额外的守护插件。

0. 环境准备

项目	要求
服务器	Linux（CentOS 7+ / Ubuntu 20.04+ / Debian 11+），1 核 1G 起
面板	宝塔 Linux 面板 7.9.3+（建议使用最新版本），已安装 Nginx
文件	clearlove-linux-amd64（或 arm64），无需在服务器安装 Go 环境

1. 上传二进制文件

1. 面板左侧「文件」→ 进入 /www/wwwroot/ → 新建目录 clearlove
2. 上传 clearlove-linux-amd64（或 arm64），重命名为 clearlove
3. 右键该文件 →「权限」→ 设为 755（或勾选「所有用户可执行」）

服务器上不需要安装 Go 环境，也不用先手动试运行，直接在下一步交给面板托管。

2. 到「Go项目」里新建项目

面板左侧「网站」→ 顶部标签切到「Go项目」→「添加项目」，对照下表填写弹窗即可：

弹窗字段	填写内容	说明
项目执行文件	选择 /www/wwwroot/clearlove/clearlove	点右侧文件夹图标选中刚上传的二进制
项目名称	clearlove	仅用于面板标识，不要使用中文
项目端口	16868	程序真实监听端口；勾选右侧「放行端口」后可直接用 IP:16868 访问
执行命令	clearlove	本项目无启动参数，按提示「默认请输入执行文件名」填写
环境变量	保持「无」	数据会生成在项目目录下；如需换路径见下方折叠说明
运行用户	www	无特殊需求保持默认
开机启动	✅ 勾选	面板自带守护进程，约 120 秒检测一次
项目备注	表白墙	非必填，可留空
绑定域名	留空或填你的域名	见下一步；留空时用 IP:16868 访问也可

「环境变量」选择「指定变量」，添加：

CLEARLOVE_DATA_DIR=/www/wwwroot/clearlove/data
CLEARLOVE_UPLOAD_DIR=/www/wwwroot/clearlove/uploads

💡 启动报 cannot execute binary file：多为架构不匹配（amd64 / arm64 传错）或没有执行权限，重新下载对应架构并 chmod +x 即可。 💡 提示端口被占用：不要填 80 / 443，这两个端口已被 Nginx 占用，本项目保持 16868 即可。 💡 权限异常时在终端执行一次：chown -R www:www /www/wwwroot/clearlove。

保存后 Go项目 列表中状态显示「运行中」即部署完成，此时即可访问 http://服务器IP:16868/install 进入安装向导。

3.（可选）绑定域名与 HTTPS

• 只用 IP 访问：第 2 步勾选「放行端口」后访问 http://服务器IP:16868，接着跳到第 5 步完成安装向导即可。
• 用域名 + HTTPS：推荐第 2 步把「绑定域名」留空，改用下面的「站点 + 反向代理」方式（这样可以顺带申请证书）；若直接在 Go项目 里填写域名，注意面板提示中域名默认为 80 端口，会和已占用 80 的 Nginx 冲突。

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（只用 IP 访问时用 http://服务器IP:16868/install）：

• SQLite：直接下一步（数据文件位于 /www/wwwroot/clearlove/data/clearlove.db）
• MySQL：先在面板「数据库」中新建一个库（如 clearlove，字符集 utf8mb4），然后在向导中填写 主机 127.0.0.1、端口 3306、库名、用户名、密码

最后填写网站名称与管理员账号，完成安装。

6. 上传大文件的调整

前台允许上传单个 ≤70MB 的视频。若上传报 413 / 失败，请调大 Nginx 请求体上限：

站点 →「配置文件」，在 server { ... } 中加入并保存（宝塔会自动重载 Nginx）：

client_max_body_size 100m;

7. 备份与升级

• 备份：面板「计划任务」→ 添加「备份目录」，分别备份 /www/wwwroot/clearlove/data 与 /www/wwwroot/clearlove/uploads（或使用 MySQL 备份任务）
• 升级：上传新的二进制覆盖 /www/wwwroot/clearlove/clearlove → 回到「网站 → Go项目」点击「重启」即可，data/ 与 uploads/ 保持不动

宝塔部署常见问题

现象	排查方向
Go项目 启动失败：cannot execute binary file	架构不匹配（amd64 / arm64 传错）或没有执行权限：重下对应架构并 chmod +x
Go项目 启动失败：提示端口被占用	不要填 80 / 443（已被 Nginx 占用），本项目保持 16868
域名访问 502 Bad Gateway	Go项目 状态是否为「运行中」；终端里 ./clearlove 能否跑起来；反向代理「目标 URL」端口是否与「项目端口」一致
安装向导无法写入数据库	目录权限：chown -R www:www /www/wwwroot/clearlove，确认 data/ 可写
上传视频失败	站点「配置文件」里调大 client_max_body_size；确认磁盘剩余空间充足
后台看到所有 IP 都是 127.0.0.1	确认通过宝塔「反向代理」转发（程序读取 X-Forwarded-For / X-Real-IP 取真实 IP）
端口 16868 想改成别的	「Go项目 → 项目端口」与「反向代理 → 目标 URL」两处需同时修改

方式一：安装「进程守护管理器」（Supervisor）

软件商店 → 官方应用 → 搜索「进程守护管理器」→ 安装，再「添加守护进程」：

字段	填写内容
名称	clearlove（不要用中文）
启动用户	www
运行目录	/www/wwwroot/clearlove
启动命令	/www/wwwroot/clearlove/clearlove

进程日志位于 /www/server/panel/plugin/supervisor/log。

方式二：直接使用 systemd

不使用面板托管时，可以写一个 systemd 单元（/etc/systemd/system/clearlove.service）：

[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

systemctl daemon-reload
systemctl enable --now clearlove
systemctl status clearlove

---

🐳 Docker 部署

二进制为 CGO_ENABLED=0 静态编译，可直接在 alpine 等最小镜像中运行，无需自己写 Dockerfile：

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            # 插件开发总览（两种形态、安装配置、权限与安全）
    ├── PLUGIN-DECLARATIVE.md# 声明式插件开发指南（hooks 钩子）
    ├── PLUGIN-APP.md        # 应用型插件开发指南（JS 运行时与 API 参考）
    └── PLUGIN-V3.md         # 插件系统设计与实现说明（内核开发者）

运行时生成（不在版本库中，升级时请勿删除）：

目录	内容
data/	config.json、SQLite 数据库、主题、插件
uploads/	图片（自动转 WebP）与视频，按日期分子目录

---

🧩 插件生态

为站点安装插件

后台「插件管理 → 插件商店」，云端地址默认 https://clearlove.kazx.top（可在「网站设置」中修改）。

安装流程：拉取市场列表 → 下载 zip → SHA256 完整性校验 → 落盘 → 回到插件管理页「启用」。

内置插件

插件	形态	说明	安装方式
背景音乐	声明式	管理员上传音乐后，访客打开站点即可听到背景音乐	后台「插件管理」上传 dist/plugin-bgm.zip
AI 语句美化	应用型	发帖页一键调用站点已接入的 AI 模型润色帖子内容（含限流、撤销）	后台「插件管理」上传 zip（plugin.json + main.js + polish.html）
每日签到	应用型	自定义数据表 + 前台页面 + 后台菜单 + 定时任务的完整示例	可将 plugins/signin/ 目录直接复制到 data/plugins/ 后启用

应用型插件（"kind": "app"）通过 main.js 注册路由、数据表、后台菜单与定时任务， 能力不受声明式钩子限制；开发指南见 docs/PLUGIN-APP.md， 两种形态的分工见 docs/PLUGIN.md。

背景音乐用法：上传 zip → 启用 → 在「插件设置」中上传音乐并保存。

zip 内 plugin.json 与 player.html 需位于压缩包根目录（不要再套一层文件夹）。 仓库 dist/ 目录不纳入版本库，可自行打包：cd plugins/bgm && zip -r ../../plugin-bgm.zip .

浏览器会拦截带声音的自动播放，插件已做兜底：被拦截时播放按钮旁会出现「点击开启背景音乐」提示， 访客点击一次即可播放；站内翻页会接着播（进度记在会话里），关闭状态也会被记住。 支持自动播放 / 循环 / 默认音量（0-100）/ 悬浮按钮位置（右下 / 左下）设置，按钮会自动避开右下角的发帖按钮。

开发并发布插件

插件就是一个包含 plugin.json 的 zip 包：

{
  "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 / admin_plugins_top	向页面头部 / 底部 / 后台插件页注入 HTML
filter	content_filter	正则改写帖子与评论内容
http	post_created / comment_created / report_created	事件 Webhook（POST JSON，带 X-ClearLove-Event 头）
guard	compose_guard	发帖守卫：命中昵称时强制验证后台管理员账号，通过后才允许发布
badge	post_badge	给指定昵称的帖子打上自定义标识

插件还可在 config 中声明配置项，后台「插件管理 → 插件设置」会自动渲染表单， 钩子字段用 {config:key} 引用配置值（guard / badge / html 钩子均支持）。

配置项类型：text / textarea / switch / select / number / audio（音频上传，含试听与旧文件自动清理）。 较长的 HTML / JS 片段可放在插件目录的独立文件中，html 字段写成 "@player.html" 即可，无需在 JSON 里转义。

发布流程：在云端 https://clearlove.kazx.top/dev/register 注册开发者（邮箱验证）→ 开发者后台上传 zip → 管理员审核上架 → 所有站点即可一键安装。详见 docs/PLUGIN.md。

---

❓ 常见问题

不需要。程序自带 HTTP 服务，直接 ./clearlove 就能用 http://IP:16868 访问。反向代理只是为了得到 80/443 端口与 HTTPS 证书。

个人站或日活不高的社区用默认 SQLite 即可，零配置、备份就是复制 data/ 目录；已有 MySQL 或需要多实例共享数据时再选 MySQL。

不会。替换二进制后重启即可，程序启动时会自动执行幂等的建表 / 索引迁移，data/ 与 uploads/ 目录保持不变。

删除 data/config.json（不含数据库文件本身），然后重新访问 /install，在向导中选择与原来完全相同的数据库配置，即可新建一个管理员账号 —— 建表迁移是幂等的，原有帖子、用户与设置都不会丢失。

⚠️ 向导中若改选了另一种数据库或另一个库，程序会连到新的库，请务必与首次安装时保持一致。

不是。默认关闭，需在后台「网站设置 → AI 模型接入」中填写兼容 OpenAI 的服务地址、密钥与模型名后才会生效。

---

📚 文档

• 主题开发 —— 目录结构与 CSS 变量
• 插件开发总览 —— 两种插件形态怎么选、打包安装与权限安全
• 声明式插件指南 —— hooks 钩子规范、示例与调试
• 应用型插件指南 —— JS 运行时、Host API 参考、Slot / 事件 / 过滤器清单

---

🔐 安全

• 密码使用 bcrypt 存储，会话为 HMAC 签名 Cookie（无状态，用户 30 天 / 管理员 12 小时）
• 所有写操作校验 CSRF 双提交令牌（API Key 调用除外）
• 用户输入统一剥离 HTML 标签，模板输出自动转义
• 数据库访问全部使用参数化 SQL
• 上传做扩展名、体积与数量校验；图片经解码重编码为 WebP
• 支持按 IP / 浏览器指纹 封禁，AI 与管理员操作全程留痕

如发现安全问题，请通过仓库 Issue 私下联系维护者，感谢你的负责披露。

---

📄 许可

本项目基于 MIT License 开源。

如果这个项目对你有帮助，欢迎点一个 ⭐ Star