写字台（xiezitai）项目总结

一、一句话介绍

写字台 是一套自托管博客系统，主打两件事：对 SEO 友好、对 AI 友好。

它既是一个能直接部署上线的个人博客，也是一个对外开放的内容底座——外部系统可以通过 REST API 发布文章，AI 可以通过 MCP 直接写文章、查文章。

• 官网：https://xiezitai.cn
• 源码：https://github.com/zhongdaiqi/xiezitai
• 镜像：https://hub.docker.com/r/zhongdaiqi/xiezitai

二、技术栈

三、功能一览

四、安全设计

把「自托管」当回事，安全能力是按真实攻击面一项项加的：

1. 两步验证：管理员可开启 TOTP，扫码或手填密钥绑定。
2. 登录失败阶梯锁定：连续错 3 次锁 5 分钟、5 次锁 10 分钟、10 次锁 1 小时。
3. 全量请求日志：所有请求留痕，可按来源、路径、状态回看。
4. 媒体不直出：上传的图片/视频不交给 Web 服务器直接暴露，而是经应用输出并记录访问日志，谁在什么时候访问了什么一目了然。
5. 上传白名单 + 魔数扫描：普通用户默认只能传图片、视频，按文件头识别真实类型，防止改名的木马；管理员不受限，并可给用户配置类型限制。
6. 文件安全扫描：扫描全部上传文件，既能发现恶意文件，也能揪出「没经过系统上传」的散落文件。
7. 防篡改：对程序自身做基线校验，识别是否被改动。

部署时的关键一条：JWT 密钥必须自己设置。不设会落到内置默认值，任何人都能伪造登录令牌。数据库密码、JWT 密钥、AI Key 等一律通过环境变量注入，镜像里不写死任何生产配置。

五、AI 能力

• 后台可配置任意 OpenAI 兼容的大模型接口（对话 + 文生图）。
• 已落地四个场景：文章润色纠错、自动写摘要、生成封面图（公众号 900×383 尺寸）、请求日志风险分析（用模型辅助识别异常访问）。
• 默认对接魔搭 ModelScope，其文生图是异步任务协议（先返回 task_id 再轮询），项目已自动适配，同时兼容 OpenAI 的同步返回形式。

六、开放 API 与 MCP：让外部系统和 AI 都能写博客

这是这个项目比较有意思的一块——博客不只是给人看的，也是给程序用的。

REST 发布

curl -X POST https://xiezitai.cn/api/v1/publish \
  -H "Content-Type: application/json" \
  -H "X-API-Token: <你的 Token>" \
  -d '{"title":"标题","content":"# Markdown 正文"}'

MCP 服务（JSON-RPC 2.0，工具：publish_article / list_articles / get_article）：

curl -X POST https://xiezitai.cn/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Token: <你的 Token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

支持远程 HTTP MCP 的客户端（Cursor / VS Code / Claude Code / 支持自定义连接器的 AI 客户端）：

{
  "mcpServers": {
    "xiezitai": {
      "type": "http",
      "url": "https://xiezitai.cn/api/v1/mcp",
      "headers": { "X-API-Token": "<你的 Token>" }
    }
  }
}

后台「设置 → 开放 API / MCP」会按当前登录账号把这几份配置实时生成好并支持一键复制，Token 和站点地址都替你填好，不用手抄。

Token 等同于账号（可发布文章），请勿贴到公开场合；怀疑泄露时在后台改一次密码即可让它失效。

七、五种部署方式，从云服务器到 1 核 1G 小机器

低配机那一版是认真测算过的：MariaDB 关掉 performance_schema、各 buffer pool 按几十 MB 的库调小；JVM 换 SerialGC、压栈到 512k、Tomcat 线程数降到 20、连接池降到 4 条。实测系统 + 数据库 + 应用三部分合计空闲约 510MB、压测后约 540MB，连打 300 次首页 + 60 次 API 全程无 OOM、零重启。

八、项目结构

src/main/java/cn/xiezitai/
 ├─ controller/   接口（含开放 API / MCP / 媒体输出）
 ├─ service/      业务（Markdown、通知、AI、安全扫描、防篡改、分发）
 ├─ security/     JWT、TOTP、登录失败锁定、请求日志过滤器
 ├─ repository/   Spring Data JPA
 ├─ entity/       实体
 └─ config/       默认数据初始化
src/main/resources/
 ├─ templates/    SEO 服务端渲染模板
 └─ static/       admin.html（ByteMD 管理后台）+ vendor/（本地内置前端依赖）
e2e/             Playwright 端到端脚本
tools/           CI 与联调小工具

九、质量保障与 CI/CD

• 集成测试：覆盖 SEO 页面、登录失败锁定（3/5/10 次）、TOTP、文章发布与草稿隔离、登录用户评论待审与审核、页面上线、上传类型限制与魔数扫描、媒体访问留痕、开放 API 与 MCP、首页搜索、请求日志、管理端权限。
• 端到端测试：Playwright + 真实 Chrome，覆盖后台建文发布、评论两级与审核、首页分页、媒体上传、视频插入、改密、记住登录、TOTP 绑定、示例内容种子、文章分发等场景。
• CI/CD：GitHub Actions 双 job —— 先原生跑一次 Maven 打好 JAR，再分别装进 amd64 与 arm64 基础镜像（避免在 QEMU 里跑 Maven，慢 5～10 倍），推送 Docker Hub；镜像构建成功后自动 SSH 到服务器执行部署脚本。

十、写在最后

写字台本来的出发点只是「想要一个自己能完全掌控的博客」，做着做着往三个方向长了出去：安全（自托管的数据和账号得自己守住）、SEO（内容得能被搜到）、开放（内容得能被程序与 AI 用起来）。

如果你也在找一个能自己部署、又能被 AI 直接调用的博客系统，可以去仓库看看；部署文档按场景分了五套，照着选一套就行。