Ghost CMS：专业开源发布平台完全指南

┌─────────────────────────────────────────┐
│            Presentation Layer            │
│  (Handlebars Themes / Admin UI / API)   │
├─────────────────────────────────────────┤
│            Business Logic               │
│  (Ghost Core: Posts, Members, Settings)│
├─────────────────────────────────────────┤
│              Data Layer                │
│       (MySQL / SQLite + Cache)         │
└─────────────────────────────────────────┘

routes:

collections:
  /blog/:
    permalink: /blog/{slug}/
    template: index
  /podcast/:
    permalink: /podcast/{slug}/
    template: podcast

# 安装 Ghost CLI
npm install -g ghost-cli

# 创建项目目录并进入
mkdir my-ghost-blog && cd my-ghost-blog

# 本地安装（使用 SQLite，适用于开发测试）
ghost install local

# 启动
ghost start

# 系统更新
sudo apt update && sudo apt upgrade -y

# 安装 Nginx
sudo apt install nginx -y

# 安装 MySQL
sudo apt install mysql-server -y
sudo mysql_secure_installation

# （可选）安装 Redis：仅在启用 Redis 缓存时使用
sudo apt install redis-server -y

# 安装 Node.js 22.x
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install nodejs -y

# 安装 Ghost CLI
sudo npm install -g ghost-cli

sudo mysql

CREATE DATABASE ghost_prod;
CREATE USER 'ghostuser'@'localhost' IDENTIFIED BY 'your_strong_password';
GRANT ALL PRIVILEGES ON ghost_prod.* TO 'ghostuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

sudo adduser --system --group ghost
sudo chown -R ghost:ghost /var/www/ghost

sudo -u ghost -H bash
cd /var/www/ghost
ghost install

ghost start          # 启动 Ghost
ghost stop           # 停止 Ghost
ghost restart        # 重启 Ghost
ghost ls             # 列出实例及运行状态
ghost update         # 更新 Ghost（出问题可 ghost update --rollback）
ghost config         # 显示当前配置
ghost log            # 查看日志
ghost check-update   # 检查是否有可用更新

# docker-compose.yml
services:
  ghost:
    image: ghost:6
    container_name: ghost-blog
    restart: unless-stopped
    ports:
      - "2368:2368"
    environment:
      url: https://yourblog.com
      database__client: mysql
      database__connection__host: db
      database__connection__user: ghost
      database__connection__password: ghost_password
      database__connection__database: ghost
    volumes:
      - ./content:/var/lib/ghost/content
    depends_on:
      - db

  db:
    image: mysql:8
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: ghost
      MYSQL_USER: ghost
      MYSQL_PASSWORD: ghost_password
    volumes:
      - ./mysql:/var/lib/mysql

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - ghost

docker-compose up -d

# 安装 cloudflared
brew install cloudflare/cloudflare/cloudflared  # macOS
# 或
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared && sudo mv cloudflared /usr/local/bin/

# 创建隧道
cloudflared tunnel create ghost-tunnel

# 配置 DNS（自动完成）
cloudflared tunnel route dns ghost-tunnel yourblog.com

# 运行隧道
cloudflared tunnel run --token <your-tunnel-token>

server {
    listen 80;
    server_name yourblog.com;

    location / {
        proxy_pass http://127.0.0.1:2368;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

{
  "url": "https://yourblog.com",
  "server": {
    "port": 2368,
    "host": "127.0.0.1"
  },
  "database": {
    "client": "mysql",
    "connection": {
      "host": "localhost",
      "port": 3306,
      "user": "ghostuser",
      "password": "your_password",
      "database": "ghost_prod"
    }
  },
  "mail": {
    "transport": "SMTP",
    "options": {
      "service": "SendGrid",
      "auth": {
        "user": "apikey",
        "pass": "your_sendgrid_api_key"
      }
    }
  },
  "storage": {
    "active": "S3Storage",
    "S3Storage": {
      "bucket": "your-bucket-name",
      "region": "ap-northeast-1",
      "accessKeyId": "your_access_key",
      "secretAccessKey": "your_secret_key",
      "cdnUrl": "https://cdn.yourblog.com",
      "staticFileURLPrefix": "content/images",
      "multipartUploadThresholdBytes": 52428800,
      "multipartChunkSizeBytes": 10485760
    }
  },
  "members": {
    "stripe": {
      "secretKey": "sk_live_xxx",
      "webhookSecret": "whsec_xxx"
    }
  },
  "privacy": {
    "useTinfoil": true
  }
}

export url="https://yourblog.com"
export database__connection__host="prod-db-host"
export database__connection__password="super_secret"
export mail__from="[email protected]"

my-theme/
├── package.json            # 主题元数据
├── README.md
├── LICENSE
├── assets/
│   ├── css/
│   │   └── screen.css     # 主样式文件
│   ├── js/
│   │   └── script.js       # 主脚本文件
│   └── images/
│       └── logo.png
├── partials/               # 模板片段
│   ├── header.hbs
│   ├── footer.hbs
│   ├── post-card.hbs
│   └── members/           # 会员相关片段
│       ├── signin.hbs
│       └── signup.hbs
├── default.hbs             # 默认布局（主模板）
├── index.hbs               # 首页模板
├── post.hbs                # 单篇文章模板
├── page.hbs                # 页面模板
├── tag.hbs                 # 标签归档模板
├── author.hbs              # 作者归档模板
└── 404.hbs                 # 404 页面

{
  "name": "my-custom-theme",
  "version": "1.0.0",
  "description": "A custom Ghost theme",
  "demo": "https://demo.ghost.io",
  "screenshots": {
    "desktop": "assets/screenshot-desktop.png"
  },
  "author": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "engines": {
    "ghost": ">=5.0.0",
    "node": ">=22.12.0"
  },
  "keywords": [
    "ghost",
    "theme"
  ]
}

{{!-- 循环输出文章列表 --}}
{{#foreach posts}}
  <article>
    <h2><a href="{{url}}">{{title}}</a></h2>
    <p>{{excerpt words="30"}}</p>
    <img src="{{feature_image}}" alt="{{title}}">
    <time datetime="{{published_at}}">{{date format="YYYY年MM月DD日"}}</time>
    {{#if @member.paid}}
      <span class="badge">付费会员专属</span>
    {{/if}}
  </article>
{{/foreach}}

{{!-- 条件判断 --}}
{{#if @site.members_enabled}}
  <a href="#/portal/signup">订阅更新</a>
{{/if}}

{{!-- 分页 --}}
{{pagination}}

{{!-- partials/post-card.hbs --}}
<article class="post-card">
  <h2><a href="{{url}}">{{title}}</a></h2>
  <p>{{excerpt}}</p>
</article>

{{!-- 在任意模板中复用 --}}
{{#foreach posts}}
  {{> "post-card"}}
{{/foreach}}

# 安装 GScan
npm install gscan -g

# 校验主题目录
gscan /path/to/my-theme

curl "https://yourblog.com/ghost/api/content/posts/?key=your_public_api_key"

{
  "posts": [
    {
      "id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "uuid": "65a1b2c3-d4e5-f6a7-b8c9-d0e1f2a3b4c5",
      "title": "Hello World",
      "slug": "hello-world",
      "html": "<p>这是文章内容...</p>",
      "custom_excerpt": "文章摘要",
      "feature_image": "https://yourblog.com/content/images/2024/hello.jpg",
      "featured": false,
      "status": "published",
      "published_at": "2024-01-15T08:00:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "url": "https://yourblog.com/hello-world/",
      "tags": [
        { "name": "技术", "slug": "tech" }
      ],
      "authors": [
        { "name": "John Doe", "slug": "john" }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "pages": 5,
      "total": 42,
      "next": 2,
      "prev": null
    }
  }
}

curl "https://yourblog.com/ghost/api/content/posts/?key=xxx&filter=tag:tech"

curl "https://yourblog.com/ghost/api/content/posts/?key=xxx&filter=author:john"

# 用 openssl 手搓一个 HS256 JWT
# 假设 API Key 为：5fdc1e0e5f2f1ab:8a9bcdef0123456789abcdef01234567
# （id 在前半，secret 为十六进制编码的 HMAC 密钥）
ID="5fdc1e0e5f2f1ab"
SECRET_HEX="8a9bcdef0123456789abcdef01234567"
NOW=$(date +%s)
EXP=$(($NOW + 300))   # 有效期最长 5 分钟

HEADER=$(printf '{"alg":"HS256","kid":"%s","typ":"JWT"}' "$ID" | openssl base64 -A | tr '+/' '-_' | tr -d '=')
PAYLOAD=$(printf '{"aud":"/admin/","exp":%s,"iat":%s}' "$EXP" "$NOW" | openssl base64 -A | tr '+/' '-_' | tr -d '=')
SIGNING_INPUT="$HEADER.$PAYLOAD"
SECRET=$(printf '%s' "$SECRET_HEX" | xxd -r -p | openssl base64 -A)
SIG=$(printf '%s' "$SIGNING_INPUT" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$SECRET_HEX" -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

TOKEN="$SIGNING_INPUT.$SIG"
echo "$TOKEN"

curl -X POST "https://yourblog.com/ghost/api/admin/posts/" \
  -H "Authorization: Ghost $TOKEN" \
  -H "Accept-Version: v6.0" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [{
      "title": "My New Article",
      "html": "<p>Article content here...</p>",
      "status": "draft"
    }]
  }'

curl -X PUT "https://yourblog.com/ghost/api/admin/posts/article-id/" \
  -H "Authorization: Ghost $TOKEN" \
  -H "Accept-Version: v6.0" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [{
      "status": "published",
      "published_at": "2024-01-15T08:00:00.000Z",
      "updated_at": "2024-01-15T09:00:00.000Z"
    }]
  }'

curl "https://yourblog.com/ghost/api/admin/members/?limit=100" \
  -H "Authorization: Ghost $TOKEN" \
  -H "Accept-Version: v6.0"

npm install @tryghost/content-api @tryghost/admin-api

const GhostContentAPI = require('@tryghost/content-api');

// 初始化
const api = new GhostContentAPI({
  url: 'https://yourblog.com',
  key: 'your_public_api_key',
  version: 'v6.0'
});

// 获取文章
async function getPosts() {
  const posts = await api.posts.browse({
    limit: 10,
    fields: ['title', 'slug', 'excerpt', 'published_at']
  });
  console.log(posts);
  return posts;
}

// 获取单篇文章
async function getPost(slug) {
  const post = await api.posts.read({
    slug: slug
  }, {
    fields: ['title', 'html', 'og_image']
  });
  return post;
}

// 获取标签
async function getTags() {
  const tags = await api.tags.browse({ limit: 20 });
  return tags;
}

getPosts().catch(console.error);

const GhostAdminAPI = require('@tryghost/admin-api');

const api = new GhostAdminAPI({
  url: 'https://yourblog.com',
  key: 'your_integration_api_key', // 完整格式：id:secret
  version: 'v6.0',                 // 客户端会自动用该 Key 生成签名 JWT
});

// 创建文章
async function createPost() {
  const post = await api.posts.add({
    title: 'My New Post via SDK',
    html: '<p>Content goes here...</p>',
    status: 'draft',
    tags: ['tech', 'nodejs']
  });
  console.log('Created post:', post.id);
  return post;
}

// 发布文章
async function publishPost(postId) {
  const post = await api.posts.edit({
    id: postId,
    status: 'published'
  });
  return post;
}

// 获取会员
async function getMembers() {
  const members = await api.members.browse({
    limit: 100,
    fields: ['id', 'email', 'name', 'subscriptions']
  });
  return members;
}

createPost().catch(console.error);

# Ghost Admin 中配置：
# Event: post.published
# Target URL: https://your-app.com/webhooks/ghost
# Secret: your_webhook_secret

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, headers) {
  const signature = headers['x-ghost-signature'];
  const secret = 'your_webhook_secret';

  if (!signature) return false;

  // header 形如 "sha256=abc123..., t=1715982456"
  const [shaPart, tPart] = signature.split(', ');
  const receivedHash = shaPart.replace('sha256=', '');
  const timestamp = tPart.replace('t=', '');

  const expectedHash = crypto
    .createHmac('sha256', secret)
    .update(`${rawBody}${timestamp}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(receivedHash),
    Buffer.from(expectedHash)
  );
}

# 更新 Ghost
ghost update

# 查看日志
ghost log               # 查看运行日志（位于 content/logs/）

# 数据库备份
mysqldump -u ghostuser -p ghost_prod > backup_$(date +%Y%m%d).sql

# 同时备份 content 目录（图片、主题等）
tar -czf content_$(date +%Y%m%d).tar.gz /var/www/ghost/content

# 检查配置
ghost config

{
  "server": {
    "port": 4368
  }
}

{
  "privacy": {
    "useTinfoil": true
  }
}

# /etc/nginx/nginx.conf
http {
    limit_req_zone $binary_remote_addr zone=ghost_api:10m rate=10r/s;

    server {
        location /ghost/api/ {
            limit_req zone=ghost_api burst=20 nodelay;
        }
    }
}

# 检查可用更新
ghost check-update

# 执行更新；若新版本异常，回滚到上一个版本
ghost update
ghost update --rollback

# 自动更新脚本（crontab）
# 0 3 * * 0 /usr/local/bin/ghost update >> /var/log/ghost-update.log 2>&1