Ghost 保姆级部署教程：开源 Headless Node.js CMS，自托管专业发布平台

一、项目介绍

Ghost 是一款以 Node.js 编写的开源 Headless CMS（内容管理系统），官方 README 副标题为"Fiercely independent, professional publishing"——主打"独立、专业的发布平台"。它由 Ghost Foundation 维护，定位是面向新闻、通讯、付费会员与订阅制内容站的现代化博客/杂志/Newsletter 平台，区别于传统重型博客系统，Ghost 将后台（Admin）与前台（Site）分离，可同时作为传统博客与 Headless API 后端使用。

官方 README 与文档显示：Ghost 在 GitHub（TryGhost/Ghost）持续活跃维护，每周都有版本发布；官方提供托管服务 Ghost(Pro)，同时开源代码允许用户用官方 Ghost-CLI 工具在自有服务器上自托管。官方文档《How To Install Ghost On Ubuntu》明确推荐生产环境栈为 Ubuntu 22.04 / 24.04 / 26.04 + NGINX + MySQL 8.0/8.4 + Node.js（受支持版本，文档示例为 Node.js 22）+ systemd，服务器最低 1GB 内存。

二、功能拆解

按官方 README 与文档，Ghost 核心能力如下：

三、官方/GitHub 链接

• GitHub 仓库：https://github.com/TryGhost/Ghost
• 官方网站：https://ghost.org/
• 官方文档：https://docs.ghost.org/
• 本地安装文档：https://docs.ghost.org/install/local/
• Ubuntu 生产安装文档：https://docs.ghost.org/install/ubuntu/
• 配置文档：https://docs.ghost.org/config/
• 升级文档：https://docs.ghost.org/update/
• 官方论坛：https://forum.ghost.org/
• Ghost(Pro) 托管：https://ghost.org/pricing/

四、环境要求

官方文档区分两种安装路径，要求不同：

本地（开发）安装（《Install Locally》）：

• 操作系统：macOS、Windows 或 Linux
• Node.js：受支持版本（见官方"supported version"链接）
• 包管理器：yarn 或 npm
• Python 3 与 setuptools（用于构建 SQLite3）
• 一个干净、空的目录
• 端口：默认 2368（本地开发）
• 数据库：自动初始化的 SQLite3，位于 /content/data/
• 模式：development（低缓存），日志仅输出到 stdout

Ubuntu 生产安装（《Install On Ubuntu》）：

• 操作系统：Ubuntu 22.04、Ubuntu 24.04 或 Ubuntu 26.04
• NGINX：最低 1.9.5（SSL 需要）
• MySQL：8.0 或 8.4
• Node.js：受支持版本（文档示例为 22）
• systemd
• 服务器内存：至少 1GB
• 已注册域名，并提前配置 DNS A 记录指向服务器 IP（用于 Let's Encrypt 自动签证书）
• 官方不支持其他操作系统作为生产自托管方案

五、部署步骤

方式 A：本地一键安装（官方 README Quickstart + Install Locally 文档）

步骤 1：全局安装 Ghost-CLI

npm install ghost-cli@latest -g

逐段解释：npm install 通过 npm 安装包；-g 表示全局安装，使 ghost 命令在任何目录下可用；ghost-cli@latest 安装官方 CLI 工具最新版（官方 README 原文为 npm install ghost-cli -g，本地安装文档原文为 npm install ghost-cli@latest -g，二者等价、后者固定拉取最新）。

预期输出参考： npm 安装进度条，结束时输出安装路径与 added N packages 之类的常规 npm 提示。

步骤 2：进入一个空目录并执行本地安装

ghost install local

逐段解释：ghost install 调用 Ghost-CLI 安装；local 标志为官方 README 与本地安装文档明确给出的本地模式开关——以 development 模式启动、自动配置 SQLite3、不设置 NGINX/SSL/systemd。官方文档原文："Once the install is finished you'll be able to access your new site on http://localhost:2368"。

预期输出参考： 安装进度日志，结束后命令行回到提示符；站点就绪在 http://localhost:2368，后台 http://localhost:2368/ghost。

步骤 3：访问站点

浏览器打开 http://localhost:2368（前台）与 http://localhost:2368/ghost（后台）。官方文档原文："your publication is setup in development mode with less caching; the SQLite3 database is auto-setup and located in /content/data/; logs only go to stdout"。

方式 B：Ubuntu 生产安装（官方《Install On Ubuntu》文档）

步骤 1：以 root 登录服务器并新建部署用户

ssh root@your_server_ip
adduser <user>
usermod -aG sudo <user>
su - <user>

逐段解释：ssh root@... 远程登录服务器；adduser <user> 按提示创建新用户（官方文档特别警告："Using the user name ghost causes conflicts with the Ghost-CLI, so it's important to use an alternative name"——用户名不要叫 ghost）；usermod -aG sudo <user> 将其加入 sudo 组；su - <user> 切换到该用户继续操作。

预期输出参考： adduser 交互式提示输入密码与个人信息；切换用户后命令行提示符变成 <user>@<host>。

步骤 2：更新系统包

sudo apt-get update
sudo apt-get upgrade

逐段解释：官方文档原文两步——apt-get update 刷新软件包索引；apt-get upgrade 升级已安装包（会提示输入新建用户的密码）。

步骤 3：安装 NGINX

sudo apt-get install nginx
sudo ufw allow 'Nginx Full'

逐段解释：apt-get install nginx 安装反向代理（SSL 需要 NGINX ≥ 1.9.5）；若系统启用了 ufw 防火墙，ufw allow 'Nginx Full' 同时放行 HTTP 与 HTTPS。

步骤 4：安装 MySQL 并给 root 设置密码

sudo apt-get install mysql-server
sudo mysql

进入 MySQL 后执行：

ALTER USER 'root'@'localhost' IDENTIFIED WITH 'caching_sha2_password' BY '<your-new-root-password>';
FLUSH PRIVILEGES;
exit

逐段解释：Ubuntu 新版本的 MySQL root 默认走 socket 认证，Ghost 不支持该方式——官方文档明确要求把 root 改成密码认证：ALTER USER ... IDENTIFIED WITH 'caching_sha2_password' BY '<password>'；FLUSH PRIVILEGES; 使授权立即生效；exit 退出 MySQL。

步骤 5：安装 Node.js 22（官方文档命令）

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
NODE_MAJOR=22
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt-get update
sudo apt-get install nodejs -y

逐段解释：前 4 行导入 NodeSource GPG 公钥到 /etc/apt/keyrings/nodesource.gpg；NODE_MAJOR=22 指定官方受支持的大版本；echo ... | sudo tee ... 写入 apt 源列表；最后 apt-get update && apt-get install nodejs -y 安装 Node.js 22。

步骤 6：全局安装 Ghost-CLI

sudo npm install ghost-cli@latest -g

逐段解释：与方式 A 相同的 CLI 安装；生产环境需 sudo。安装后可运行 ghost help 查看全部命令。

步骤 7：创建专属部署目录

sudo mkdir -p /var/www/sitename
sudo chown <user>:<user> /var/www/sitename
sudo chmod 775 /var/www/sitename
cd /var/www/sitename

逐段解释：官方文档明确要求 Ghost 必须安装在自己的目录、并设好属主与权限：mkdir -p /var/www/sitename（sitename 可改）；chown <user>:<user> 把属主设为当前部署用户；chmod 775 设置权限；cd 进入该目录。

步骤 8：执行生产安装向导

ghost install

逐段解释：官方文档原文"Now we install Ghost with one final command"。安装向导会依次询问：

• Blog URL：站点对外完整 URL（含 https://，例如 https://example.com），用 IP 会报错。
• MySQL hostname：同机 MySQL 直接回车用默认 localhost。
• MySQL username / password：用 root 则输入 root 与上一步设置的密码。
• Ghost database name：数据库名，非 root 用户时需手工预先建好。
• Set up a ghost MySQL user? (Recommended)：选 yes，让 CLI 创建仅能访问该库的专用 MySQL 用户。
• Set up NGINX? (Recommended)：yes 自动配置 NGINX。
• Set up SSL? (Recommended)：URL 为 https 且域名已解析时，CLI 自动用 Let's Encrypt 签证书（需邮箱用于续期通知）。
• Set up systemd? (Recommended)：yes 注册 systemd 服务，实现开机自启与崩溃拉起。
• Start Ghost?：yes 立即启动站点。

预期输出参考： 向导完成后官方文档原文："Your Ghost site is now live! To set up your admin account, go to https://example.com/ghost"。

六、配置参数详解

1. 配置文件（官方《Configuration》文档）：

• 本地/开发：config.development.json
• 生产：config.production.json
• 开发时附加覆盖：config.local.json（叠加在 development 之上，不进 git）
• 文件位于 Ghost 安装根目录；改完用 ghost restart 生效。

2. 必填配置项（官方配置表格）：

3. 数据库配置示例（官方原文）：

MySQL 生产配置：

"database": {
  "client": "mysql",
  "connection": {
    "host": "127.0.0.1",
    "port": 3306,
    "user": "your_database_user",
    "password": "your_database_password",
    "database": "your_database_name"
  }
}

SQLite3 本地配置：

"database": {
  "client": "sqlite3",
  "connection": {
    "filename": "content/data/ghost-test.db"
  },
  "useNullAsDefault": true,
  "debug": false
}

4. 监听端口配置（官方原文）：

"server": {
  "host": "127.0.0.1",
  "port": 2368
}

解释：默认 127.0.0.1:2368——NGINX 反向代理 80/443 到该端口。官方文档说明："By default, requests are routed from port 80 to Ghost by nginx (recommended)"。

5. 邮件配置示例（Mailgun，官方原文）：

"mail": {
  "transport": "SMTP",
  "options": {
    "service": "Mailgun",
    "host": "smtp.mailgun.org",
    "port": 465,
    "secure": true,
    "auth": {
      "user": "postmaster@example.mailgun.org",
      "pass": "1234567890"
    }
  }
}

解释：官方配置文档给出的示例；改完保存后 ghost restart 生效。文档同时提醒：DigitalOcean 默认封 25/465/587、Google Cloud 封 25，若邮件发送超时需换端口。

6. 环境变量覆盖（官方原文）： 所有配置项都可用同名环境变量覆盖，嵌套字段用双下划线：

url=http://ghost.local:2368 node index.js
database__connection__host=mysql node index.js

七、启动与运维

• 启动 / 停止 / 重启（官方本地安装文档与 CLI）：
• ghost start：启动
• ghost stop：停止
• ghost restart：重启（改完配置文件后用）
• ghost ls：列出所有运行中的 Ghost 实例
• ghost log：查看日志

• ghost help：查看全部命令

• 后台常驻与开机自启： 生产安装向导中"Set up systemd? (Recommended)"选 yes 即由官方注册 systemd 服务——这是官方提供的开机自启与崩溃拉起方式。本地（local）安装模式官方文档原文："Ghost runs in a separate background process and remains running until you stop it or restart your computer"，即本地模式由 CLI 自身派生后台进程，重启电脑后需手动 ghost start。

• 修改端口： 修改 config.production.json 的 server.port（如 2368），并在 NGINX 配置中同步 upstream 端口；同时保证 url 与外部访问一致。官方文档提示："If you see errors such as access denied from url, then the provided URL in your config file is incorrect and needs to be updated"。

• 数据持久化： 所有站点内容（数据库、主题、图片、日志）位于安装目录下的 content/ 子目录；SQLite3 模式数据库文件在 content/data/；生产 MySQL 模式数据落在 MySQL 数据目录，content/ 仍存放主题与上传文件。备份时同时备份 content/ 目录与 MySQL 库。

• 查看日志： ghost log（官方本地安装文档）；日志文件位于 content/logs/（配置文档 logging.path 项）。

八、实操验证

本地安装验证（方式 A）：

1. 安装完成后浏览器访问 http://localhost:2368，看到 Ghost 默认前台主题（Casper）首页。
2. 访问 http://localhost:2368/ghost，官方文档原文："that's it! You're done"——进入 Ghost Admin 后台。
3. 首次访问 /ghost 会提示创建站点所有者账号（邮箱、密码、博客标题），按提示填写后即进入写作后台。
4. 在后台写一篇测试文章并发布，回到 http://localhost:2368 前台可看到该文章。

生产安装验证（方式 B）：

1. DNS A 记录已将 example.com 指向服务器 IP，ghost install 向导选了 NGINX + SSL + systemd。
2. 浏览器访问 https://example.com，应看到默认主题首页（HTTPS 证书由 Let's Encrypt 签发，浏览器地址栏显示安全锁）。
3. 访问 https://example.com/ghost，按官方文档原文"go to https://example.com/ghost. When you get there, you'll be prompted to create your account as the site owner"——首次进入创建站点所有者账号。
4. 验证 systemd 守护：在服务器执行 sudo systemctl restart ghost_<sitename> 或直接 ghost restart，站点自动恢复；重启服务器后站点随 systemd 自启。

登录与安全（重要）

• 官方默认账号密码：无出厂账号。 Ghost 第一次访问 /ghost 时由用户自己创建站点所有者（Site Owner）账号——邮箱与密码均在首次设置时由用户填写，不存在默认 admin/admin。
• 登录地址： 本地为 http://localhost:2368/ghost；生产为 https://你的域名/ghost（路径固定为 /ghost/，官方配置文档原文："it can't affect the path at which the admin panel is served (this is always /ghost/)"）。
• 首次登录后修改密码： 登录后台 → 左下角「设置（Settings）」→「用户（Users）」→ 点自己的用户名 → 修改密码。
• 密码重置： 在登录页点击"Forgot password"，Ghost 通过配置好的 mail SMTP 向注册邮箱发送重置链接（因此生产环境必须配置 mail，官方配置文档把 mail 列为生产必填项）。
• 密码配置存放位置： 密码以哈希形式存储在数据库中（生产为 MySQL 的 users 表，本地为 content/data/ 下的 SQLite3 文件）；配置文件 config.production.json 中不保存明文密码，只保存 SMTP 凭据等。
• 安全提醒：
  1. 部署完成后首次进入 /ghost 创建的站点所有者账号务必使用强密码。
  2. 官方配置文档明确："We always recommend using SSL to run your Ghost publication in production. Without SSL your username and password are sent in plaintext"——生产务必走 HTTPS（向导自动签 Let's Encrypt 证书）。
  3. 公网部署注意 url 配置必须与实际外部域名一致，否则会出现 access denied from url 类错误。

九、故障排查

案例 1：Blog URL 用 IP 导致安装失败

• 报错原文（常见形式）：Blog URL must be a valid URL 或安装过程中提示 URL 不正确、NGINX/SSL 步骤失败。
• 报错原因：官方《Install On Ubuntu》文档明确："Enter the exact URL your publication will be available at and include the protocol for HTTP or HTTPS. For example, https://example.com. If you use HTTPS, Ghost-CLI will offer to set up SSL for you. Using IP addresses will cause errors."
• 分步解决：① 准备好域名并配置 DNS A 记录指向服务器 IP；② 重新执行 ghost install，在 Blog URL 处填写 https://你的域名；③ 若已失败，按官方文档"if an install goes horribly wrong, use ghost uninstall to remove it and try again"，先 ghost uninstall 清理后重装。

案例 2：MySQL root socket 认证导致 Ghost 无法连接

• 报错原文（常见形式）：ERROR (code ER_ACCESS_DENIED_ERROR): Access denied for user 'root'@'localhost' (using password: YES) 或安装向导在 MySQL 步骤中断。
• 报错原因：官方文档原文："On newer versions of Ubuntu, the root user created when you install MySQL will by default be configured to use socket-based authentication... Ghost does not support this kind of authentication, so you must change the root MySQL user to have a password."
• 分步解决：① 进入 MySQL：sudo mysql；② 执行 ALTER USER 'root'@'localhost' IDENTIFIED WITH 'caching_sha2_password' BY '<your-new-root-password>';；③ FLUSH PRIVILEGES;；④ exit；⑤ 重新运行 ghost install，在 MySQL 密码处输入刚设置的密码。

案例 3：访问后台报 access denied from url

• 报错原文：Access denied from url（官方配置文档原文引用）。
• 报错原因：官方配置文档原文："If you see errors such as access denied from url, then the provided URL in your config file is incorrect and needs to be updated"——config.production.json 中的 url 与实际访问的域名/端口不一致。
• 分步解决：① 编辑 config.production.json，把 url 改为实际对外访问的完整 URL（含协议、含正确端口）；② ghost restart 生效；③ 若通过反向代理改了端口，同时检查 admin.url 配置。

案例 4：本地安装 Python/SQLite3 构建失败

• 报错原文（常见形式）：gyp ERR!、node-pre-gyp 或 SQLite3 编译报错。
• 报错原因：官方本地安装文档前置要求列出"Python 3 and setuptools for building SQLite3"。环境缺失则 SQLite3 原生模块无法编译。
• 分步解决：① 按官方前置要求安装 Python 3 与 setuptools（如 Debian/Ubuntu：sudo apt-get install python3 python3-setuptools build-essential）；② 删除安装目录后重新 ghost install local。

十、升级、回滚与卸载

升级（官方《Update Ghost》文档原文）：

ghost check-update
ghost backup
ghost update

逐段解释：ghost check-update 检查是否有新版本（官方原文："you can find out whether new updates are available any time by running ghost check-update"）；ghost backup 升级前先备份（官方："If you want to be super safe, run ghost backup first"）；ghost update 执行升级。

官方文档同时给出版本升级路径表：3.x/4.x/5.x 且生产用 MySQL 的站点可直接 ghost update 升到 6.x；低于 3.0.0、或任何生产用 SQLite3 的站点需要完整重装。MariaDB 用户建议先迁到 MySQL 8。

回滚： 官方未提供一键回滚命令；升级前的 ghost backup 即官方推荐的回滚保障——若升级后异常，可基于备份恢复。也可在 Ghost-CLI 目录下手动将版本固定到旧 tag 后重新安装（非官方明示命令，仅基于 npm 包版本机制）。

卸载（官方《Install On Ubuntu》文档原文）：

ghost uninstall

逐段解释：官方文档原文："If an install goes horribly wrong, use ghost uninstall to remove it and try again. This is preferable to deleting the folder to ensure no artifacts are left behind."——即官方提供的卸载方式是 ghost uninstall，而不是直接 rm -rf 目录。

如需彻底清理：① 先 ghost backup 或手动备份 content/ 目录与 MySQL 库；② ghost uninstall；③ 删除 /var/www/sitename 目录；④ 按需 sudo apt-get remove nginx mysql-server（非 Ghost 官方命令，仅通用系统清理）。

十一、商用许可合规说明

• 许可证：MIT License（官方仓库 LICENSE 文件原文："Copyright (c) 2013-2026 Ghost Foundation - Released under the MIT license"）。
• MIT 许可允许自由使用、修改、分发与商用（包括闭源商业产品），但必须保留原始版权声明与许可文本。
• 商标注意： 官方 README 明确："Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our trademark policy for info on acceptable usage"——代码可自由商用，但"Ghost"名称与 Logo 的使用须遵守 Ghost Foundation 的商标政策（https://ghost.org/trademark/）。
• Ghost Foundation 同时提供 Ghost(Pro) 付费托管服务作为可选商业渠道，自托管开源版本无需付费授权。