把用了多年的 Typecho 保留为后台内容管理，前端换成 Astro 静态渲染——这就是本站现在的架构。这篇文章记录完整的改造思路与踩坑。

阅读剩余部分

博客这种小服务，最怕的不是流量大，而是搬家与数据丢失。用 Docker Compose 把 Typecho 和数据库固定下来，再配一个定时备份，一劳永逸。

基础编排

services:
  typecho:
    image: joyqi/typecho:nightly-php8.3
    restart: always
    ports:
      - "8080:80"
    volumes:
      - ./usr:/app/usr
    depends_on:
      - db
  db:
    image: mariadb:11
    restart: always
    environment:
      MARIADB_ROOT_PASSWORD: change-me
      MARIADB_DATABASE: typecho
    volumes:
      - ./db:/var/lib/mysql

定时备份

数据库用 mysqldump，附件目录直接打 tar 包：

#!/usr/bin/env bash
set -euo pipefail
STAMP=$(date +%F-%H%M)
DEST=/backups/${STAMP}
mkdir -p "${DEST}"

docker compose exec -T db sh -c   'exec mariadb-dump -uroot -p"${MARIADB_ROOT_PASSWORD}" typecho'   > "${DEST}/typecho.sql"

tar -czf "${DEST}/usr.tgz" ./usr

# 只保留最近 14 份
ls -1dt /backups/*/ | tail -n +15 | xargs rm -rf

crontab 里加一行，每天凌晨 3 点执行：

0 3 * * * cd /srv/blog && ./backup.sh >> /var/log/blog-backup.log 2>&1

常见问题

坚持「配置即文件」的原则，搬家时 git clone + docker compose up -d 两步就能恢复。

记录 typecho-api 插件常用端点，方便前端直连调试。

端点速查

GET /index.php/api?token=***&method=getbloginfo      站点信息
GET /index.php/api?token=***&method=getarticle       文章列表（分页）
GET /index.php/api?token=***&method=getcomments&cid=1 文章评论
GET /index.php/api?token=***&method=getallcategories 全部分类
GET /index.php/api?token=***&method=getalltags       全部标签
GET /index.php/api?token=***&method=search&keyword=x 搜索

响应结构

{
  "success": true,
  "data": [
    {
      "cid": 1,
      "title": "欢迎使用 Typecho",
      "slug": "start",
      "categories": ["默认分类"],
      "tags": [],
      "summary": "如果您看到这篇文章…",
      "text": "<!--markdown-->如果您看到这篇文章…"
    }
  ],
  "pagination": { "total": 1, "page": 1, "pageSize": 10 }
}

注意事项

1. 所有请求都要带 token
2. text 是原始 Markdown，带 <!--markdown--> 前缀
3. 分页 pageSize 上限为 50
4. 插件没有 CORS 头，浏览器端直连会被拦，需服务端转发

站点完成无头化改造后的第一篇文章，也是渲染链路的冒烟测试。

冒烟清单

• 标题、日期、分类、标签展示正常
• Markdown 渲染无异常
• 评论表单可以提交
• 搜索可以命中这篇文章

如果你能看到这一行，说明整条「Typecho API → Astro 构建 → 浏览器渲染」链路是通的。🎉