jiang13-forum/README.md

姜十三论坛 Jiang13 Forum

能聊 · 好看 · 好装

面向小圈子、团队与同好社群的轻量现代化论坛。
编译为单个 Go 二进制，前端 SPA（单页应用）内嵌，内置 SQLite，拷到服务器即可运行。

在线演示 · 快速开始 · 界面预览 · 功能亮点 · 路线图 · 参与贡献

_{浅色主题 · 三栏布局 · Feed 排序 · 板块导航 · 标签云}

演示站点： https://bbs.iioio.com/
项目积极开发中。管理后台已统一为 React SPA（/admin），欢迎提 Issue / PR 共建。

---

它是什么

姜十三论坛不做大而全的社区平台，只做好一件事：给「几人到几百人」的内部交流，一个干净、顺手、数据在自己手里的地方。

场景	说明
团队 / 工作室	需求讨论、进度同步、知识沉淀
兴趣小圈子	同好交流、作品分享、活动组织
项目配套社区	可与 Gitea 等通过 OIDC（开放身份连接）做 SSO（单点登录）
个人站长	单机可跑，无需云数据库与一堆微服务

---

界面预览

截图来自演示站 bbs.iioio.com。

浅色主题 左栏板块 · Feed 排序 · 右栏热门 / 标签 / 评论	暗色主题 一键切换 · 护眼阅读 · 全局色彩自适应
帖子详情 文章目录 · 标签 · 作者卡片 · 修订信息	富文本渲染 TipTap 排版 · 图片 · 代码高亮 · 目录导航

移动端 — 板块快捷筛选 · Feed 排序 · 触控友好列表

---

功能亮点

界面与交互

特性	说明
三栏布局	左栏板块导航 + 中间虚拟滚动帖列表 + 右栏热门 / 标签 / 最新评论
虚拟滚动	@tanstack/react-virtual 驱动长列表，浏览依然流畅
帖子排序	最新发帖 / 最新回复 / 热门讨论
主题切换	浅色 / 暗色，跟随系统偏好并本地记忆
响应式	平板 / 手机自动收起侧栏，搜索、发帖、登录触手可及

社区功能

• 用户注册 / 登录（bcrypt + JWT Cookie）；首个注册用户自动成为管理员
• 板块、发帖、TipTap 富文本、正文图片上传、标签、置顶 / 精华
• 帖子修订历史与 diff（差异）对比；可配置普通用户编辑时限
• 楼层式评论：回复指定楼层、@ 高亮、引用回复；支持回复可见等内容门控
• 点赞、收藏、热门帖、最新评论、站内私信、公开用户主页
• 管理后台：仪表盘、删帖 / 删评、禁言、举报、敏感词、限流、SQLite 一键备份
• 可选：邮件验证码、OIDC Provider、Gitea 仓库同步（开源码桶）、S3 兼容对象存储

部署体验

• 单二进制 — go:embed 打包前端，无需再单独部署静态资源
• 零依赖数据库 — SQLite 内建，数据目录由 app.ini 统一管理
• 跨平台 — Windows / Linux / macOS 一键编译
• 系统服务 — 内置 Linux systemd / Windows Service 注册
• Docker 单容器 — 多阶段镜像，挂载 data/ 即可持久化

---

快速开始

1. 编译

Windows（推荐）：

build.bat

请通过 build.bat 调用（内部已处理 ExecutionPolicy）。不要直接 .\build.ps1，也不要在 Windows 上使用系统自带的 Embarcadero make。

Linux / macOS：

make build

手动分步（全平台）：

cd frontend && npm install && npm run build
cd .. && go build -trimpath -ldflags "-s -w" -o dist/jiang13 ./cmd/jiang13

跨平台编译：

build.bat -Target build-windows
build.bat -Target build-linux
build.bat -Target build-all

2. Docker 部署（推荐）

一键启动（本地构建）：

docker compose up -d --build

.\build.bat -Target compose-up

make compose-up

浏览器打开 http://localhost:3000/register 注册；首个用户自动成为管理员。

拉取已构建镜像（Docker Hub）：

docker pull hangzhang714128/jiang13-forum:latest
docker run -d --name jiang13 \
  -p 3000:3000 \
  -v jiang13-data:/data \
  --restart unless-stopped \
  hangzhang714128/jiang13-forum:latest

数据持久化： 容器内 /data 对应 SQLite、上传、日志与 JWT 密钥，与下方「数据目录」结构一致。可用 Docker volume 或绑定宿主机目录。镜像启动时会自动将 /data 卷属主修正为 uid 1000（jiang13 用户），适配 1Panel 等面板挂载的目录。

若使用旧版镜像仍报 permission denied，可在宿主机执行：chown -R 1000:1000 /你的数据目录

可选环境变量（容器编排）：

变量	说明
JIANG13_HTTP_PORT	HTTP 端口（默认 3000）
JIANG13_DATA	数据目录（默认 /data）
JIANG13_JWT_SECRET	JWT 密钥（留空则自动生成并写入 /data/.jwt_secret）
JIANG13_CONFIG	配置文件路径
JIANG13_WORK_PATH	工作目录

健康检查： GET /health 返回 {"status":"ok"}，供 Docker / 负载均衡探活。

CI 自动构建镜像： 向 GitHub main 分支 push 或打 v* 标签后，GitHub Actions 会构建并推送到 Docker Hub。需在 GitHub 仓库 Secrets 中配置 DOCKERHUB_USERNAME 与 DOCKERHUB_TOKEN（Access Token，需 Read & Write 权限）。

手动推送：

docker login
docker build --build-arg VERSION=1.0.0 -t hangzhang714128/jiang13-forum:1.0.0 -t hangzhang714128/jiang13-forum:latest .
docker push hangzhang714128/jiang13-forum:1.0.0
docker push hangzhang714128/jiang13-forum:latest

停止服务：docker compose down / .\build.bat -Target compose-down / make compose-down

构建失败（无法连接 auth.docker.io）？ Dockerfile 已默认经 DaoCloud 拉取基础镜像。若仍超时，可在 Docker Desktop → Settings → Docker Engine 添加：

{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

保存并重启 Docker 后重试 .\build.bat -Target docker。PowerShell 中请用 .\build.bat（带 .\ 前缀）。

1Panel 部署提示：

1. 容器镜像填 hangzhang714128/jiang13-forum:latest
2. 端口映射 3000:3000
3. 挂载数据卷到容器内 /data（镜像会自动修正目录权限）
4. 首次访问 http://服务器IP:3000/register 注册管理员

3. 直接启动（二进制）

把二进制放到目标目录后直接运行（首次会在同目录生成 app.ini）：

# Windows
.\dist\jiang13.exe

# Linux / macOS
./dist/jiang13

也可先复制示例配置再改端口 / 数据目录：

cp app.ini.example /opt/jiang13/app.ini
# 编辑 app.ini 后：
./jiang13

4. 首次使用

1. 浏览器打开 http://localhost:3000/register 注册账号
2. 第一个注册的用户自动成为管理员
3. 登录后访问 http://localhost:3000/admin 进入后台

配置文件（app.ini）

默认读取工作目录下的 app.ini（工作目录默认可执行文件所在目录）。

[server]
HTTP_PORT = 3000

[paths]
DATA = data

[security]
JWT_SECRET =

完整示例见 app.ini.example。OIDC、邮件、Gitea 同步、对象存储等请在管理后台「系统设置」配置（保存即生效）。

优先级： 命令行显式参数 > app.ini > 内置默认值。

启动参数

参数	默认值	说明
--work-path	可执行文件目录	工作目录（app.ini 与相对 DATA 的基准）
--config	{work-path}/app.ini	配置文件路径
--port	（读配置 / 3000）	HTTP 监听端口
--data	（读配置 / data）	数据目录
--jwt-secret	自动生成	JWT 签名密钥（留空则持久化到 data/.jwt_secret）
--service	（空）	install / uninstall / start / stop / restart / status

环境变量（容器 / 编排，优先级低于命令行）： JIANG13_HTTP_PORT、JIANG13_DATA、JIANG13_JWT_SECRET、JIANG13_CONFIG、JIANG13_WORK_PATH

5. 注册为系统服务（可选）

将二进制与 app.ini 放到同一目录后注册即可。之后改端口或数据目录只需编辑 app.ini 并重启服务，不必重新安装。

Ubuntu / Linux（systemd，需 root）：

sudo mkdir -p /opt/jiang13
sudo cp jiang13 /opt/jiang13/
sudo /opt/jiang13/jiang13 --service install
sudo /opt/jiang13/jiang13 --service start
sudo systemctl enable jiang13

Windows（Windows Service，需管理员 PowerShell）：

New-Item -ItemType Directory -Force -Path C:\jiang13 | Out-Null
Copy-Item .\jiang13.exe C:\jiang13\
C:\jiang13\jiang13.exe --service install
C:\jiang13\jiang13.exe --service start

改 app.ini 后执行 --service restart。运行日志写入数据目录下的 jiang13.log。

---

技术栈

层级	技术
后端	Go 1.26 · Gin · GORM · SQLite
前端	React 18 · TipTap · Radix UI · Tailwind CSS · TanStack Virtual
构建	Vite → go:embed 内嵌 SPA，单二进制发布
认证	bcrypt · JWT Cookie · 可选 OIDC Provider

---

前端开发

日常改前端不需要重新完整构建，Vite 支持秒级热更新（HMR，热模块替换）：

build.bat -Target dev

make dev

浏览器访问 http://localhost:5173，API 自动代理到 http://localhost:3000。

何时需要完整构建：

• 修改 Go 代码或要发布单二进制 → build.bat / make build
• 更新 README 界面截图 → 见下方「更新截图」

直接访问 :3000 看到的是上次 build 嵌入的前端；开发时请用 :5173。

更新截图

默认从演示站抓取到 docs/screenshots/（需本机已安装 Playwright）：

npm install -D playwright
npx playwright install chromium
node scripts/capture-screenshots.mjs

环境变量	说明	默认
J13_URL	抓取目标	https://bbs.iioio.com
J13_POST_ID	详情页帖子 ID	1
J13_RICH_POST_ID	富文本展示帖 ID	8
J13_USER / J13_PASS	发帖页登录（可选）	admin / admin123

本地站点示例：J13_URL=http://localhost:3000 node scripts/capture-screenshots.mjs

---

项目结构

jiang13-forum/
├── cmd/jiang13/           # 程序入口（含系统服务注册）
├── config/                # app.ini 与命令行配置
├── app.ini.example        # 配置文件示例
├── Dockerfile             # 多阶段 Docker 构建
├── docker-compose.yml     # 单容器 Compose 部署
├── docker-entrypoint.sh   # 容器启动脚本（修正 /data 卷权限）
├── .dockerignore
├── model/                 # GORM 模型与数据库迁移
├── service/               # 业务逻辑
├── handler/               # HTTP 处理器（前台 + 后台）
├── middleware/            # JWT 鉴权等
├── router/                # 路由注册
├── embed_static/          # go:embed 内嵌的 SPA
├── frontend/              # React 源码（Vite 构建）
├── docs/screenshots/      # README 界面截图
├── ROADMAP.md             # 路线图与已知问题
└── scripts/               # 开发辅助脚本（含截图）

---

数据目录

data/
├── jiang13.db              # SQLite 主数据库
├── jiang13.log             # 运行日志
├── filter_words.txt        # 敏感词配置
├── .jwt_secret             # JWT 密钥（自动生成）
├── uploads/avatars/        # 用户头像
├── uploads/posts/          # 帖子正文图片
└── jiang13_backup_*.db     # 后台导出的备份

---

开发状态

项目积极开发中，欢迎参与共建。完整列表见 ROADMAP.md。

类型	示例
✅ 已可用	三栏布局、暗色主题、虚拟滚动、Feed 排序、楼层评论
✅ 发帖体验	TipTap 富文本、图片上传、修订历史、回复可见等门控
✅ 管理后台	React SPA：仪表盘、置顶 / 精华、禁言、系统设置
📋 计划中	通知动态优化、邮件提醒

---

参与贡献

欢迎提交 Issue 和 Pull Request！详见 CONTRIBUTING.md。

在线体验与反馈也可直接在演示站进行：https://bbs.iioio.com/

---

许可证

MIT — 自由使用、修改与分发。