Furtalk 是一个自托管的网站评论系统。后端提供完整的评论 API 与管理能力,拥有独立的管理控制台,支持匿名评论、认证评论与人工审核等多种部署形态。
- 轻量可自托管:单二进制进程,支持 SQLite 与 PostgreSQL,可选 Redis 缓存。
- 可嵌入:评论组件为独立 ES module,Shadow DOM 隔离样式,按页面键挂载即可使用。
- 多身份体系:密码、邮箱验证码、Passkey(WebAuthn)与主流 OAuth/OIDC 提供商。
- 可运营:站点/线程/用户管理、评论审核与垃圾标记、邮件通知、CAPTCHA 保护。
- 匿名与认证两种评论模式,可全局或按页面开关评论。
- 审核策略:直接发布或人工审核;垃圾标记与恢复。
- 认证方式:
- 邮箱 + 密码、邮箱一次性验证码;
- Passkey(WebAuthn);
- OAuth/OIDC:GitHub、Google、GitLab、Microsoft、Twitter、Gitea、Apple、Discord、LINE、Mastodon 及自定义 OIDC。
- CAPTCHA 支持 Turnstile、reCAPTCHA、hCaptcha 与 CAP,可按动作(登录、评论等)独立配置。
- 邮件通知:回复、审核发布、密码重置与登录验证码,模板化渲染。
- 多站点管理:支持接入多个站点。
- 隐私控制:IP / User-Agent 捕获粒度可配置。
- 邮箱域名白名单 / 黑名单,Gravatar 头像,远程表情目录(emoji-pack 协议)。
- 统一的 JSON 错误信封、限流、可信代理、优雅关闭与安全响应头。
| 层 | 技术 |
|---|---|
| 后端 | Go ≥ 1.27.3、Gin、GORM、go.uber.org/fx、Viper |
| 数据库 | SQLite(纯 Go glebarez 驱动)或 PostgreSQL(pgx) |
| 缓存 | 进程内缓存(默认)或 Redis |
| 认证 | golang-jwt(HS256)、WebAuthn、go-oidc |
| 邮件 | go-mail(SMTP) |
| 迁移 | Atlas Community v1.3.0 Versioned SQL |
| 前端 | Web 控制台:React 19 + Vite + TanStack Router;评论组件:Lit + Shadow DOM |
cmd/app 服务入口(fx 装配)
internal/app 组合根:生命周期、就绪检查、依赖装配
internal/domain 领域类型与错误 sentinel
internal/handler HTTP 处理器与请求/响应 DTO
internal/router 路由与全局中间件(安全头、限流、鉴权等)
internal/service 业务用例(bootstrap / comment / identity / notification / setting / site)
internal/repository 数据持久化
internal/platform 跨领域基础设施(config / database / cache / token / oauth / captcha / mailer ...)
configs 配置模板与邮件模板
migrations 数据库迁移(sqlite / postgres)
docs API 契约、迁移说明与 Swagger 生成物
web/ 管理控制台 SPA(子模块,见 web/README.md)
widget/ 可嵌入评论组件(子模块,见 widget/README.md)
- Go ≥ 1.27.3
- pnpm(构建 Web 与 Widget)
- Task(推荐,
task命令;详见 Taskfile.yml) - Atlas Community v1.3.0(非容器部署手动迁移需要;官方镜像已内置,见
docs/database-migrations.md)
task build # 后端 + Web + Widget 全量构建
go build ./... # 仅构建后端(不包含 Web 资源)
go run ./cmd/app # 以开发默认值启动,不开启内嵌 Web普通后端构建不会读取 Web 子模块或 Node 依赖。需要生成带控制台的二进制时,先构建并暂存 Web 产物,再显式使用 embed build tag:
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
./scripts/stage-web.sh
CGO_ENABLED=0 go build -tags embed -o furtalk ./cmd/app
./furtalk --web-
准备静态配置。全部必需项来自配置文件或
FURTALK_前缀环境变量,模板见configs/config.example.yaml;配置优先级:非空环境变量 > 配置文件 > 内置默认值。 必需项:FURTALK_HTTP_PUBLIC_BASE_URL— 实例公开 Origin(OAuth、退订链接等)FURTALK_DATABASE_DIALECT—sqlite或postgres- SQLite:
FURTALK_DATABASE_PATH - PostgreSQL:
FURTALK_DATABASE_HOST/FURTALK_DATABASE_PORT/FURTALK_DATABASE_NAME/FURTALK_DATABASE_USER/FURTALK_DATABASE_PASSWORD/FURTALK_DATABASE_SSL_MODE FURTALK_TOKENS_JWT_ISSUER/FURTALK_TOKENS_JWT_KEYFURTALK_TOKENS_SECRET_KEY— Provider 机密加密主密钥FURTALK_WEBAUTHN_RP_ID/FURTALK_WEBAUTHN_RP_ORIGINS
-
使用官方 Docker 镜像时,入口脚本会自动执行一次已提交的 versioned migration apply。直接运行二进制或使用自定义镜像时,仍需在应用进程外先完成 schema 迁移。应用二进制本身不会建表:
atlas migrate apply --dir "file://migrations/sqlite" --url "<目标 SQLite URL>" # PostgreSQL: atlas migrate apply --dir "file://migrations/postgres" --url "<目标 PostgreSQL URL>"
-
启动应用。全新实例的启动日志会打印一次性 setup token(10 分钟内有效)。
-
访问
/setup页面,填写 setup token、管理员邮箱、昵称与密码完成初始化,之后跳转/login登录。
迁移细节(备份、dry-run、既有库 baseline 接管等)见
docs/database-migrations.md。
根目录 docker-compose.yml 提供一个使用 GHCR 官方镜像的 SQLite 单服务部署。数据保存在命名卷中的 /app/data/furtalk.db;宿主机的 ./configs 会只读挂载到容器内 /app/configs,用于提供可选的 config.yaml 和邮件模板。先复制配置模板到未跟踪的 .env 并替换必需值,再启动:
cp configs/.env.example .env
# 编辑 .env,替换 JWT、Provider 加密和 WebAuthn 等占位值
docker compose up -d如需使用 YAML 配置,可将 configs/config.example.yaml 复制为 configs/config.yaml。邮件模板位于 configs/email,应用只在启动时加载模板,修改后需重启容器。
默认使用稳定镜像 latest;可通过 FURTALK_IMAGE_TAG=1.2.3 固定已发布版本,也可用 FURTALK_IMAGE 指定完整镜像引用。
启动时从配置文件和(或)环境变量一次性加载静态配置。完整 YAML 模板见 configs/config.example.yaml,以下为环境变量速查表。
| 环境变量 | 级别 | 默认 | 说明 |
|---|---|---|---|
FURTALK_HTTP_ADDRESS |
建议 | :8080 |
HTTP 监听地址 |
FURTALK_HTTP_PUBLIC_BASE_URL |
必需 | — | 实例公开 Origin(OAuth/退订链接等) |
FURTALK_HTTP_TRUSTED_PROXIES |
建议 | 空 | 可信代理 CIDR 列表 |
FURTALK_HTTP_BODY_LIMIT |
建议 | 1048576 |
请求体上限(字节) |
FURTALK_HTTP_RATE_LIMIT_RATE/BURST |
建议 | 10/100 |
令牌桶 |
FURTALK_HTTP_SHUTDOWN_TIMEOUT |
建议 | 10s |
优雅关闭宽限 |
FURTALK_DATABASE_DIALECT |
必需 | — | sqlite | postgres |
FURTALK_DATABASE_PATH |
条件必需 | — | sqlite 时的数据库文件路径 |
FURTALK_DATABASE_HOST |
条件必需 | — | postgres 主机;sqlite 时忽略 |
FURTALK_DATABASE_PORT |
条件必需 | — | postgres 端口(1-65535) |
FURTALK_DATABASE_NAME |
条件必需 | — | postgres 数据库名 |
FURTALK_DATABASE_USER |
条件必需 | — | postgres 用户名 |
FURTALK_DATABASE_PASSWORD |
条件必需 | — | postgres 密码 |
FURTALK_DATABASE_SSL_MODE |
条件必需 | — | postgres SSL mode |
FURTALK_CACHE_REDIS_URL |
可选 | 空 | 空 = 进程内缓存 |
FURTALK_TOKENS_JWT_ISSUER |
必需 | — | JWT issuer |
FURTALK_TOKENS_JWT_ALGORITHM |
建议 | HS256 |
固定 HS256 |
FURTALK_TOKENS_JWT_KEY |
必需 | — | 原始文本密钥,≥ 32 字节 |
FURTALK_TOKENS_JWT_LIFETIME |
建议 | 168h |
第一方 JWT 有效期 |
FURTALK_TOKENS_WIDGET_JWT_LIFETIME |
建议 | 24h |
评论组件 JWT 有效期 |
FURTALK_TOKENS_SECRET_KEY |
必需 | — | Provider 机密加密主密钥,原始文本,≥ 32 字节 |
FURTALK_WEBAUTHN_RP_ID |
必需 | — | WebAuthn RP 标识 |
FURTALK_WEBAUTHN_RP_ORIGINS |
必需 | — | WebAuthn 允许 Origin 列表 |
FURTALK_WEBAUTHN_RP_NAME |
建议 | Furtalk |
WebAuthn RP 展示名 |
FURTALK_OAUTH_CLIENT_TIMEOUT |
建议 | 10s |
OAuth HTTP 超时 |
FURTALK_SMTP_HOST |
可选 | 空 | 空 = 通知惰性;设置后启用 SMTP |
FURTALK_SMTP_PORT/TLS/TIMEOUT |
建议(启用时) | 587/starttls/30s |
SMTP 投递参数 |
FURTALK_SMTP_FROM |
必需(启用时) | — | SMTP 发件地址 |
FURTALK_SMTP_USERNAME/PASSWORD |
可选 | 空 | SMTP 凭据 |
FURTALK_LOGGING_FORMAT |
默认 | text |
后端日志输出格式:json 或 text |
第三方 OAuth/OIDC 登录的回调入口是前端专用回调页 https://<public-origin>/oauth/callback/{provider}
后端与前端需要同源部署,共用同一 FURTALK_HTTP_PUBLIC_BASE_URL。
本地关键词库渠道(spam.local)固定从 configs/spam/keywords.txt 读取词库文件,数据库与
管理 API 不传输词库内容,也不接受词库路径:
- 文件必须是服务端可读的普通 UTF-8 文本文件;每行一个关键词或短语,忽略空行、 去首尾空白并去重,Unicode 大小写不敏感匹配。
- 大小限制:单文件不超过 64 MiB,单行不超过 4000 字节;超出则整次加载失败并保留 最近成功快照。
- 容器部署需把宿主机词库绑定到容器内的
/app/configs/spam/keywords.txt;启用spam.local前请先创建或挂载该文件。 - 运行期按文件大小与修改时间热重载,词库变更无需重启;保存配置时会立即校验文件。
评论组件是独立的浏览器 ES module,通过 Shadow DOM 隔离样式,可嵌入任意静态站点:
<script type="module" src="https://cdn.example.com/widget/furtalk.min.js"></script>
<furtalk-comments site-id="123" page-key="article-2026-08"></furtalk-comments>- 构建:
pnpm --dir widget build(task widget:build),产物包含 未压缩的widget/dist/furtalk.js和 npm/CDN 使用的压缩版widget/dist/furtalk.min.js,两者均带 source map。 - 部署:将
widget/dist/产物托管到独立 CDN / 静态托管,通过<script>加载; 组件自动从import.meta.url推导 Furtalk 服务源(可用service-origin属性覆盖)。 - 部署要求:授权流程依赖
window.opener,禁止使用noopener,也禁止对该流程设置Cross-Origin-Opener-Policy: same-origin(same-origin-allow-popups兼容); 评论会话依赖 CHIPS Partitioned cookie。 - 挂载属性与详细约定见
widget/README.md。
Web 控制台是覆盖登录、OAuth 授权、站点/线程/用户/评论管理与设置的后台 SPA,独立构建与
部署,见 web/README.md。
后端质量门由 Taskfile 封装(gofmt、vet、build、test、架构规则、CGO-free):
task build # 后端 + Web + Widget 全量构建
task check # 后端 + Web + Widget 全量质量门
task backend:check # 后端质量门
task web:check # Web 质量门
task widget:check # Widget 质量门
task release # 生成 bin/ 下四个发布二进制(linux/windows × amd64/arm64)
task test-race # 后端竞态检测测试
task docker:check # 校验 Atlas 容器入口、方言选择与镜像文件契约
docs/contract.md— HTTP 端点、认证、数据库与事件契约。docs/swagger/— Swagger 生成物(drift 检查基线)。docs/database-migrations.md— 数据库迁移流程与回滚边界。web/README.md— 管理控制台。widget/README.md— 评论组件。