如何自建博客评论系统
薛英杰 / 2026-11-17
静态博客最大的遗憾是它真的只是一堆静态文件。文章写完了、发出去了,读者读完想留一句话,却发现页面底部空空如也。这篇文章记录我用 FastAPI + MongoDB 搭一套自托管评论系统的过程:从三十行的评论接口开始,一路加到 GitHub 登录、楼层回复和表情反应,中间踩过的坑也一并写下来。
如果你也用 blogdown 或者 Hugo 写博客,又不想把评论区交给别人,这套方案可以直接照搬。
为什么不直接用现成的
最常见的两个选择是 Disqus 和 utterances,但它们各有各的别扭。
Disqus 是第三方脚本,会在你的页面里塞进一堆追踪代码,加载慢,国内能不能打开还要看运气,评论数据也不在你手里。utterances 轻得多,评论存进 GitHub Issues,但代价是每条评论都要走一次 GitHub 授权,读者没有账号就只能看不能说。
自己写的方案则简单得多:一套 HTTP 接口,数据落在本机 MongoDB,前端一个 fetch 就接上了。总代码量不到 350 行,一个人两天能写完,之后维护成本几乎为零。
最终的形态
整个链路只有四个组件:
浏览器 (comments.html)
│ HTTPS
▼
cpolar 隧道 comments.cpolar.top
│ 转发到 127.0.0.1:8001
▼
uvicorn (blog-comments.service)
│ pymongo
▼
MongoDB blog.comments / blog.reactions
| 组件 | 职责 | 选型理由 |
|---|---|---|
| Web 框架 | 路由、校验、序列化 | FastAPI 自带 pydantic 校验和交互式文档,单文件能跑 |
| 数据库 | 存评论与反应 | 评论是嵌套结构,文档模型免迁移 |
| 进程守护 | 挂了自动拉起 | systemd 用户服务,不需要 root |
| 公网入口 | 提供 HTTPS 域名 | 博客本身是 HTTPS,评论接口也必须是 |
数据库只用了两个集合:comments 存评论,reactions 存表情。索引建在 (path, created_at) 和 (approved, created_at) 上,因为所有查询都绕不开”某篇文章”和”是否已审核”这两个条件。
一、先把评论接口写出来
第一步不要想登录、不要想回复,只做一件事:能发、能读。请求体用 pydantic 声明,越界、空内容、超长内容都会被 FastAPI 挡在进入函数之前:
class CommentIn(BaseModel):
path: str = Field(..., max_length=300)
name: str = Field("", max_length=50)
content: str = Field(..., min_length=1, max_length=2000)
email: str = Field("", max_length=200)
website: str = Field("", max_length=200) # 蜜罐字段
parent_id: Optional[str] = None
入库时有两个细节值得说。
第一是不要把 _id 直接返回给前端。ObjectId 不是 JSON 可序列化类型,而且它的字符串形式和内部结构不同,前端只应该看到一个不透明的 id。所以序列化函数统一做一次转换:
def _serialize(doc):
return {
"id": str(doc["_id"]),
"name": doc["name"],
"content": doc["content"],
"parent_id": str(doc["parent_id"]) if doc.get("parent_id") else None,
"created_at": doc["created_at"].isoformat(),
}
第二是时间统一存 UTC。用 datetime.now(timezone.utc) 而不是 datetime.now(),输出 isoformat() 带时区偏移,前端 new Date() 解析后自动转成本地时间。省掉时区转换这一层,后面能少掉一半的”评论时间怎么差八小时”的问题。
至于是不是要审核,交给一个开关:
"approved": not APPROVAL_REQUIRED,
读接口永远只查 approved=True,这样审核功能就是配置项而不是分支逻辑。
二、前端只做三件事
评论区的 partial 里没有框架,只有原生 JavaScript。它需要做的其实就三件事。
一是从页面上读出接口地址,这样换域名不用改代码:
<section id="comments" data-api="{{ .Site.Params.comments.api }}">
二是拿当前路径去问后端要数据。用 location.pathname 当 key,天然和文章一一对应:
fetch(api + "/api/comments?path=" + encodeURIComponent(location.pathname))
.then(function (r) { return r.json(); })
.then(render);
三是渲染前转义。这里有一个容易被忽略的点:前端转义只防渲染时的 XSS,后端也必须剥一次 HTML。因为数据不只从你的页面来,别人可以直接 POST 一段 <script> 到接口里,存库之后所有读者都会中招。所以入库前过一遍 re.sub(r"<[^>]*>", "", text),前端再转义一次,两道关。
三、让它一直活着
开发时 uvicorn app:app --reload 就够了,但服务得有人看着。用 systemd 用户级服务,不需要 sudo,也不用写 crontab:
[Unit]
Description=Blog comments API (FastAPI, 127.0.0.1:8001)
After=network-online.target mongod.service
[Service]
WorkingDirectory=/Data/server
EnvironmentFile=/Data/server/.env
ExecStart=/usr/bin/python3 -m uvicorn app:app --host 127.0.0.1 --port 8001 \
--proxy-headers --forwarded-allow-ips=*
Restart=always
RestartSec=5
KillSignal=SIGINT
[Install]
WantedBy=default.target
里面有两处值得解释。
EnvironmentFile 把 .env 直接注入进程环境,密钥文件权限设成 600,不用在 unit 里明文写 secret。
--proxy-headers --forwarded-allow-ips=* 是因为服务躲在隧道后面,所有请求的来源 IP 都是 127.0.0.1。如果不让 uvicorn 信任 X-Forwarded-For,按 IP 限流就会变成”全站共用一个计数器”,刷五条评论所有人一起被锁。当然,反过来说,只有当你确定前置代理可信时才应该加这个参数。
服务只监听 127.0.0.1,不对公网暴露端口,公网入口完全交给隧道。
四、HTTPS 这一关:混合内容陷阱
博客是 HTTPS 的,评论接口如果不是 HTTPS,浏览器会直接拦掉请求,控制台报 mixed content。
我第一次用的是 cpolar tcp 8001,它给的是一个纯 TCP 端口,没有 TLS,前端请求全部失败。改成本地 HTTP 隧道就对了:
cpolar http -config=/usr/local/etc/cpolar/cpolar.yml -subdomain=comments 8001
隧道同样用 systemd 守护,并用 After=blog-comments.service 声明依赖顺序。这样拿到的 https://comments.cpolar.top 就可以直接写进 config.toml:
[params.comments]
enable = true
api = "https://comments.cpolar.top"
五、加上 GitHub 登录
匿名评论方便,但没法区分作者、也没法让读者删自己发的评论。加 GitHub OAuth 是性价比最高的选择:读者群体本来就多是开发者,而且 read:user 只读权限,不涉及仓库。
整个流程三步:
/api/auth/github/login生成跳转地址,把client_id、redirect_uri、scope和state拼进去;- 用户在 GitHub 授权后回跳到
/api/auth/github/callback?code=...; - 后端用
code换access_token,再用它拉用户信息,签发自己的登录态,最后跳回文章页。
换 token 那一步不需要任何 SDK,urllib 就够:
data = urllib.parse.urlencode({
"client_id": GITHUB_CLIENT_ID,
"client_secret": GITHUB_CLIENT_SECRET,
"code": code,
}).encode()
req = urllib.request.Request(
"https://github.com/login/oauth/access_token",
data=data,
headers={"Accept": "application/json", "User-Agent": "blog-comments"},
)
请求头里的 Accept: application/json 是关键,不带的话 GitHub 返回的是 key=value& 形式的表单串。
登录态没有引入 PyJWT,而是用 hmac 手写了二十来行 HS256:
def _create_token(payload):
header = _b64url(json.dumps({"alg": "HS256", "typ": "JWT"}).encode())
body = _b64url(json.dumps(payload).encode())
sig = hmac.new(JWT_SECRET.encode(), f"{header}.{body}".encode(), hashlib.sha256).digest()
return f"{header}.{body}.{_b64url(sig)}"
验证时有一个顺序问题:必须先重算签名比对,再解析 payload。如果反过来,就等于信任了未经验证的内容。比对用 hmac.compare_digest 而不是 ==,避免时序侧信道。任何异常都直接当作验证失败,返回 None。
还有一个新手常犯的错误:JWT_SECRET 要写死。最初的代码是 os.getenv("JWT_SECRET", 随机值),看着很安全,实际意味着服务每重启一次,所有登录用户的 token 全部失效。等读者发现”怎么又要登录”的时候,你未必能想到是重启导致的。
六、反垃圾的四道阀门
公开接口一定会被扫描,不需要等被刷才处理。四层防护,成本从低到高:
| 手段 | 做法 | 挡住什么 |
|---|---|---|
| 蜜罐 | 表单里放一个 CSS 隐藏的 website 输入框,非空即拒绝 |
盲目填表的小机器人 |
| 限流 | 按 IP 哈希计数,60 秒最多 5 条 | 脚本连续刷屏 |
| 剥离 HTML | 入库前正则去标签 | 存储型 XSS |
| 人工审核 | APPROVAL_REQUIRED=1 |
漏网之鱼 |
蜜罐字段的巧处在于它对用户完全不可见,真人永远不会填,而自动化工具倾向于把表单里的每个字段都填满。一个隐藏的 website 字段比任何验证码都省事,对读者零打扰。
限流的实现就在进程内存里,一个字典加时间窗:
def _rate_limit(key, window=60, limit=5):
now = time.time()
start, count = _windows.get(key, (0.0, 0))
if now - start > window:
_windows[key] = (now, 1)
return
if count >= limit:
raise HTTPException(status_code=429, detail="评论太频繁,请稍后再试")
_windows[key] = (start, count + 1)
它足够挡住随手刷屏,但要知道它的边界:字典不会自动清理,单进程有效,重启即清零。真要防有组织攻击,得换成 Redis 或者前置 WAF。
七、楼层回复的取舍
回复功能有两种实现思路:后端存树,或者后端存扁平的 parent_id。
我选了后者。后端只做三件校验——parent_id 能转成 ObjectId、父评论存在、父评论属于同一篇文章——然后原样存下。层级关系交给前端解释:
var byId = {};
items.forEach(function (item) { byId[item.id] = item; item.children = []; });
items.forEach(function (item) {
if (item.parent_id && byId[item.parent_id]) {
byId[item.parent_id].children.push(item);
}
});
好处是查询永远是”这篇文章的所有评论”一次 find,不需要递归拼接,也不需要维护嵌套数组的一致性。坏处是父评论被删除后,子评论会变成孤儿——这一条我确实踩了,后面细说。
八、用 R 检查接口
博客是用 R 写的,顺手用 R 做接口冒烟测试也很自然。httr2 几行就能验证服务是否正常:
library(httr2)
api <- "https://comments.cpolar.top"
# 健康检查
request(api) |>
req_perform() |>
resp_body_json()
# 登录入口应当返回 3xx,且 Location 指向 GitHub
request(api) |>
req_url_path_append("api", "auth", "github", "login") |>
req_url_query(return_to = "/") |>
req_options(followlocation = FALSE) |>
req_perform() |>
resp_header("location")
评论数据本身也能直接查。想看看哪几篇文章讨论最热烈:
library(mongolite)
library(ggplot2)
comments <- mongo("comments", db = "blog")
stats <- comments$aggregate('[{"$group": {"_id": "$path", "n": {"$sum": 1}}}]')
ggplot(head(stats[order(-stats$n), ], 10), aes(n, reorder(`_id`, n))) +
geom_col() +
labs(x = "评论数", y = NULL, title = "讨论最热烈的十篇文章")
用 mongolite 的好处是绕过了 HTTP 接口的审核过滤,能看到包括待审核在内的全量数据,适合做后台盘点。
九、踩过的坑
307 不是 302。 FastAPI 的 RedirectResponse 默认 status_code=307。对浏览器里的 GET 跳转来说两者等价,但如果你写脚本断言”必须是 302”,测试会失败。需要字面 302 就显式传参。
改了 .env 必须重启。 环境变量在模块 import 时就被读成常量,运行期再改文件没有任何效果。同理,.env 里的值不要和代码里的 os.getenv(..., "默认值") 打架,出问题时很难判断到底用的是哪一个。
state 参数必须签名。 我最初的实现把 state 单纯当成 base64(return_to),回调时直接跳回去。问题在于 return_to 完全由攻击者控制:构造一个指向外部站点的 state,诱导受害者完成一次授权,回调就会带着 token= 跳到攻击者的域名,登录态当场泄露。正确做法是把 state 用同一个 JWT_SECRET 签一遍,回调时先验签,或者干脆只允许相对路径。
删除评论要级联。 接口文档写的是”删除评论及其所有回复”,实现里只有 delete_one。子评论在库里留着,因为父节点没了,前端不会渲染它们,看起来像是删掉了。补一句 delete_many({"parent_id": oid}) 才是真的删干净。
表情接口要认身份。 反应接口的 user 字段由前端传,意味着任何人都能替别人点赞。小站点影响不大,但认真起来必须改成从 JWT 里取身份。
小结
整套系统大约三百多行 Python 加一个二十 KB 的前端 partial,跑在一台已经装着 MongoDB 的开发机上,用 systemd 和 cpolar 顶着公网流量。它没有 Disqus 那样的后台、没有邮件通知、没有社交登录之外的身份体系,但胜在每一行代码都看得懂、每一个字都在自己的硬盘里。
自建的意义大概就在这里:不是为了造一个更好的轮子,而是为了让”读者的留言”这件事,不需要经过第三方的服务器。
评论