简介

VanBlog 是一个用 Node.js 写的轻量个人博客系统，数据存在 MongoDB，前台服务端渲染。它的定位很明确：一条 docker-compose 起站，自带后台、图床、评论、访问统计、暗色模式和自动 HTTPS，不折腾 LNMP。

核心特点与优势：

部署极简：官方 compose 只有两个服务（VanBlog + MongoDB），内置 Caddy 负责证书，域名解析好就能自动上 HTTPS。
自带图床：上传的图片直接存在容器挂载目录里，不依赖第三方对象存储，备份目录就带走了。
后台完整：文章、分类、标签、自定义页面、导航、评论、统计、SEO 设置都在后台，手机浏览器也能写。
导入导出友好：文章可以按 Markdown 批量导出 / 导入，换机器或迁移时不至于被困住。
阅读体验好：默认主题适配移动端，自带暗色模式、目录、代码高亮，开箱就是成品的博客样子。
资源占用可控：一台 1 核 1G 的轻量服务器能跑，配比静态站高，但比 WordPress + 插件轻。

需要提前知道的：

动态系统，必须常驻服务器，不能放 GitHub Pages。
内置 Caddy 要独占 80 / 443，服务器上已有 Nginx 时要么停掉，要么改端口做前置反代。
数据在 MongoDB 和 data/ 目录里，备份是硬要求，删容器不等于删数据（但删目录等于删站）。

维度	VanBlog	Hugo / Hexo
形态	动态，Node + MongoDB	静态，构建出 HTML
写作	浏览器后台	本地 Markdown + Git
部署	服务器 + Docker	任意静态托管
HTTPS	内置 Caddy 自动签发	自己配 certbot
运维	备份数据库与图片、升级镜像	几乎为零
适合	想要后台、图床、评论的个人站	零成本、纯写作

部署

VanBlog 的部署本质是 Docker Compose 起两个容器（VanBlog + MongoDB），域名解析到服务器，Caddy 自动签证书。官网给了两个入口：

一键脚本：全新机器上一条 curl 命令生成 compose 并启动，适合先跑通再说；
手写 compose：自己控制目录、镜像版本、端口和备份位置，适合长期维护。

下面先讲脚本，再讲手动配置，最后处理「已有 Nginx」的情况。

一键脚本部署（官方）

1. 命令

在服务器上执行（官网提供的原始命令）：

bash
curl -L https://vanblog.mereith.com/vanblog.sh -o vanblog.sh && chmod +x vanblog.sh && ./vanblog.sh

脚本交互过程中会问两项：

邮箱：用于 Caddy 申请 HTTPS 证书；
HTTP 端口：默认 80，80 被占用时才改。

执行前建议先看一眼脚本内容，确认没有多余动作：

bash
less vanblog.sh

2. 脚本做了什么

按官网脚本的实际逻辑：

数据目录固定在 /var/vanblog，自动 mkdir -p 创建；
从官网下载 compose 模板为 /var/vanblog/docker-compose-template.yaml，再生成可编辑的 /var/vanblog/docker-compose.yaml；
按网络情况自动选用镜像：能连 Docker Hub 用 mereith/van-blog:latest，否则用 registry.cn-beijing.aliyuncs.com/mereith/van-blog:latest；
把数据路径、镜像地址通过 sed 写进 compose；
先 docker-compose down -v，再 docker-compose up -d 启动容器。

后续更新再执行一次 ./vanblog.sh 即可（内部会 pull 新镜像再重建）。

3. 一键脚本的注意事项

点	说明
目录固定	数据、日志、证书都在 `/var/vanblog`，备份和迁移要来这里找，不是当前目录
域名仍要自己配	脚本不处理 DNS；必须先解析 `A` 记录，否则 Caddy 签不到证书
证书依赖 80/443	端口被 Nginx 等占用时，自动 HTTPS 会失败，脚本不会替你解决冲突
用的是 `docker-compose`	旧版 v1 命令。新系统只装了 Compose v2 插件（`docker compose`）时可能提示命令不存在，需要额外装兼容包，或直接改用下面的手动 compose
`down -v`	脚本每次会先移除容器；compose 模板用的是宿主机目录挂载，数据一般不受影响，但升级前仍应先备份 `/var/vanblog`
版本是 `latest`	脚本生成的 compose 不锁版本，长期维护建议改成具体版本号
需要写 `/var`	用 `sudo` 执行，生成的文件属主可能是 root，后续编辑注意权限

4. 跑通之后

访问 https://域名/admin 完成初始化；确认站点正常后，建议把 /var/vanblog/docker-compose.yaml 里的 latest 固定成当前版本，并把备份脚本指向 /var/vanblog。

想要更可控的结构（自定义目录、前置 Nginx、固定版本），继续看下一节。

有服务器、域名

1. 前置条件

云服务器：1 核 1G 起，2G 更稳；系统 Ubuntu 22.04 / 24.04。
域名一个，国内服务器必须先完成 ICP 备案。
80 / 443 在宿主上必须是空闲的：装过 Nginx / Apache / 宝塔的机器，先停掉对应服务。
安全组和 ufw 放行 22 / 80 / 443。
已装 Docker 与 Compose 插件：

bash
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
docker compose version

2. 先解析域名

Caddy 要靠域名申请证书，解析必须先生效，否则第一次启动会卡在证书签发。

bash
dig +short blog.example.com   # 必须返回服务器公网 IP

服务商	入口	记录	注意点
Cloudflare	DNS → Records	`A blog → 服务器IP`	用 Cloudflare 代理时 SSL/TLS 设 `Full (strict)`；首次签发证书建议先灰云，签发成功再按需开橙云
阿里云 / 腾讯云	云解析 DNS → 添加记录	`A blog → 服务器IP`，TTL 600	国内服务器先备案
DNSPod	域名解析 → 添加记录	`A blog → 服务器IP`，TTL 600	等 TTL 过期再启动容器

3. docker-compose 配置

bash
mkdir -p ~/vanblog && cd ~/vanblog

docker-compose.yaml（基于官方模板，只改了邮箱和路径写法）：

yaml
services:
  vanblog:
    image: mereith/van-blog:latest
    restart: always
    environment:
      TZ: Asia/Shanghai
      # 邮箱，用于 Caddy 自动申请 HTTPS 证书
      EMAIL: someone@example.com
    volumes:
      # 图床文件
      - ./data/static:/app/static
      # 日志
      - ./log:/var/log
      # Caddy 配置
      - ./caddy/config:/root/.config/caddy
      # Caddy 证书
      - ./caddy/data:/root/.local/share/caddy
    ports:
      - 80:80
      - 443:443

  mongo:
    # 部分机器不支持 AVX，MongoDB 高版本会启动失败，官方默认用 4.4.16
    image: mongo:4.4.16
    restart: always
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./data/mongo:/data/db

要点：

EMAIL 必须换成真实邮箱，证书到期通知和 ACME 注册都用它。
国内拉镜像慢时，把镜像换成 registry.cn-beijing.aliyuncs.com/mereith/van-blog:latest。
生产环境可以把 latest 固定成具体版本号，升级时手动改，避免重启就升级。
data/、caddy/、log/ 都在当前目录下，这三个目录就是整站的数据，别放在临时目录。

4. 启动

bash
docker compose up -d
docker compose logs -f vanblog

日志里能看到 Caddy 为域名申请证书的过程。首次启动通常十几秒到一分钟，取决于 DNS 和网络。

浏览器访问 https://blog.example.com：

证书正常 → 直接进初始化页面；
证书失败 → 先退回 http://blog.example.com 或 http://IP，确认站点本身能开，再排查证书（见排错表）。

5. 初始化

首次访问会进入初始化向导（后台地址 https://blog.example.com/admin）：

设置管理员用户名和密码；
填站点名称、站点描述；
完成后进入后台，前台是默认主题。

后台里还可以继续配：站点图标、导航、分类、标签、自定义页面、评论、统计、SEO、自定义 CSS / HTML。官方演示站的 demo / demo 只用于体验，不要在生产环境沿用。

6. HTTPS 与访问方式

内置 Caddy 自动处理 HTTP → HTTPS 跳转和证书续期，不需要再装 certbot。
不要用 IP 访问 https：Caddy 是给域名签证书的，https://IP 一定报错。测试期用 http://IP。
用 IP 走 http 如果被强制跳到 https，去后台关闭「HTTPS 自动重定向」。
换域名：改 DNS → 在后台更新站点地址 → 重启容器让 Caddy 重新签证书，旧域名证书不会自动迁移。

7. 备份与升级

备份（建议每周 + 升级前必做）：

bash
cd ~/vanblog
docker compose stop vanblog
tar -czf ~/vanblog-backup-$(date +%F).tar.gz data/ caddy/ docker-compose.yaml
docker compose start vanblog

data/mongo：全部文章、设置、账号；
data/static：图床里的图片；
caddy/：证书与 Caddy 配置；
再加一份后台导出的 Markdown，作为「数据可读」的兜底。

用一键脚本部署时，把上面的 ~/vanblog 换成 /var/vanblog；脚本生成的 compose 也在那里。

升级：

bash
cd ~/vanblog
docker compose pull
docker compose up -d
docker compose logs -f vanblog

升级前先备份；升级后如果打不开，把镜像 tag 改回旧版本再 up -d 即可回滚（所以生产建议固定版本号）。

8. 检查清单

dig 解析到正确 IP，且没开 CDN 代理（首次启动）
宿主 80 / 443 没有被 Nginx / Apache 占用
EMAIL 是真实邮箱
data/、caddy/、log/ 在持久化目录里，重启容器数据还在
https://域名 证书有效，http:// 能自动跳转
后台上传一张图片，前台能正常显示
做过一次完整备份，并试过解压查看内容
服务器磁盘剩余空间 > 5G（MongoDB + 图片会持续增长）

已有 Nginx：改端口做前置反代

机器上已经跑着 Nginx 或其它占用 80 / 443 的服务时，两条路：

推荐：把 VanBlog 放到单独服务器 / 单独 IP，让它独占 80 / 443，省心且证书自动。

共存方案：让宿主 Nginx 终止 TLS，VanBlog 只提供 http 端口，证书由宿主管。

改 compose 的端口映射，只监听本机：

yaml
    ports:
      - 127.0.0.1:8080:80

启动后确认 curl -I http://127.0.0.1:8080 返回 200 或 302。
宿主 Nginx 反代（/etc/nginx/sites-available/vanblog.conf）：

nginx
server {
    listen 80;
    server_name blog.example.com;

    client_max_body_size 64m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

用宿主已有的 certbot / 面板证书给 blog.example.com 配 HTTPS。

这条路的代价：VanBlog 内置的自动 HTTPS 用不上，证书续期靠宿主；升级时两层配置都要确认没冲突。能用独立机器就别选它。

常见故障对照

现象	原因	处理
一键脚本报 `docker-compose: command not found`	系统只有 Compose v2 插件，没有旧版 `docker-compose`	装兼容包，或按「有服务器、域名」一节手写 compose 用 `docker compose`
启动报 `port is already allocated`	80 / 443 被 Nginx 等占用	停掉宿主服务，或改端口做前置反代
证书签发失败	DNS 未生效、80 被占、Cloudflare 橙云拦截	先灰云、确认 80 可达、等解析生效再重启
`https://IP` 打不开	Caddy 只给域名签证书	用域名访问，测试期用 `http://IP`
访问 http 被强制跳 https 且证书错	开启了自动跳转但证书未就绪	后台关闭「HTTPS 自动重定向」，或先把证书跑通
mongo 容器反复重启	CPU 不支持 AVX	使用 `mongo:4.4.16`（官方默认值）
图片 404	`data/static` 没挂载或权限不对	检查 volumes 路径与容器日志
后台打开空白 / 502	容器未就绪或内存不足	`docker compose logs vanblog`，加 swap 或升内存
时间显示不对	时区不是东八区	两个服务都设 `TZ: Asia/Shanghai`
磁盘满	图片和 MongoDB 增长	清理日志、压缩图片，扩容磁盘

个人博客配置

站点信息

后台 → 站点设置：站点名称、描述、Logo / favicon、备案号、页脚信息。描述会进首页 meta，是 SEO 里最直接的一项。

导航与页面

导航：后台新建导航项，指向首页、归档、分类、标签、关于；
自定义页面：适合「关于」「友链」「留言板」，支持 Markdown；
分类：文章只能属于一个分类，规划成 4～5 个稳定分类，标签随意加；
标签：在文章编辑页填写，前台自动生成标签页。

图床

VanBlog 的图片存在 data/static，后台编辑器里直接上传或粘贴图片即可：

图片地址由站点域名生成，换域名后旧图可能 404，迁移时同步改地址配置；
备份必须包含 data/static，只备份数据库会丢图；
单张图建议压缩到 300KB 以内，手机流量和首屏都受益。

评论与统计

后台可以开启内置评论与访问统计：

评论通知需要配 SMTP（发件服务器、端口、授权码），否则只有站内提醒；
开启评论审核，个人博客不适合先发后审；
统计看后台面板即可，需要第三方统计（GA4、51LA）时在自定义 HTML / 脚本注入里加。

SEO

站点描述、文章摘要必填；
检查 /sitemap.xml 与 /rss.xml 是否可访问（版本不同路径可能不同），有的话提交到搜索平台；
每篇文章填好标题、摘要、封面，分享卡片才有内容；
国内服务器记得在页脚放备案号并链接到工信部。

导入导出

后台支持 Markdown 批量导入 / 导出，VanBlog 导出的文章头是这样的：

yaml
---
title: 个人博客-hugo
category: 项目分享
tags: HuGo
updatedAt: 2026-05-31T03:52:10.452Z
createdAt: 2025-07-17T15:46:57.722Z
---

# 简介
……
<!-- more -->

三个注意点：

category 是单个值，不要写数组；
tags 是逗号分隔的字符串，不是 YAML 数组；
时间用 UTC 毫秒时间戳（带 Z），摘要分隔符是 ，导入前不要删。

从别的系统迁进来时，把 front matter 对齐成上面的格式，能省掉大量手工修正。

多端写作实现

核心模型

内容在数据库，任何浏览器登录后台即可写作。


浏览器打开 https://域名/admin → 新建文章 → 写 → 发布
        → MongoDB 保存 + 图片进 data/static → 前台立即可见

手机端

后台是响应式的，手机上可以完整地写文章、传图、改设置；
适合随手记、补图、改错字；长文排版仍然建议桌面；
图片直接从相册上传，正文插入后不要再移动文件，否则链接会断；
手机端不要做升级、改 compose、清缓存这类操作。

桌面端

浏览器多标签：一篇文章 + 图床 + 设置同时开；
写长文时先在本地 Markdown 编辑器写好再粘贴进后台，需要保留格式时用「Markdown 模式」；
批量迁移用后台导入功能，导入前按上一节的 front matter 约定整理文件名与字段。

写作纪律

固定分类 + 标签体系，别每次临时起新分类；
封面图统一比例（如 16:9），首页列表才整齐；
文章摘要手写，别依赖自动截断；
每次升级镜像前做完整备份，并记录当前版本号；
换域名时同步更新：DNS、Caddy 证书、站点地址、图床地址，四处一起改；
服务器监控磁盘，MongoDB 与图片目录只增不减，定期清理废弃附件。