VuePress Theme Plume 在 Synology DSM 上的完整部署指南

约 1855 字大约 6 分钟

进阶工具cpolarPlume

2025-10-24

📋 文档说明

本文档完整记录在 Synology DS923+ (ARM 架构) 上使用 Docker Compose 部署 VuePress Theme Plume 博客的全过程，包含所有步骤、问题排查和解决方案。官方说明：https://theme-plume.vuejs.press/

🎯 环境信息

组件	版本信息
设备	Synology DS923+
架构	ARM
DSM 版本	7.2+
Container Manager	最新版本
Node.js	20.19.5
包管理器	pnpm 10.19.0

⚠️ 已知兼容性问题

在 ARM 架构的 Synology DSM 上直接安装会遇到：

esbuild 权限错误: EACCES 权限拒绝
ARM 兼容性问题: Segmentation fault
Git 初始化问题: Exit code 129

🚀 完整部署流程

第一阶段：项目初始化

1.1 创建项目目录

# 进入工作目录
cd /xxx/xxx/plume-blog

# 查看当前目录
ls -la

1.2 创建 VuePress 项目

# 使用创建工具初始化项目
pnpm create vuepress-theme-plume@latest

配置选项选择：

✅ 项目路径: ./my-project
✅ 站点名称: Sumejss (根据实际需求修改)
✅ 站点描述: Welcome to my technical blog. (根据实际需求修改)
✅ 多语言支持: No (简化配置)
✅ 默认语言：简体中文
✅ TypeScript: Yes (推荐)
✅ 打包工具: Vite (默认)
✅ 部署类型: Custom
✅ 初始化 Git 仓库: Yes
✅ 安装依赖: Yes

⚠️ 重要：依赖安装步骤会失败，这是正常的 ARM 架构兼容性问题，我们后续通过 Docker 解决。

1.3 处理创建失败后的项目

创建完成后，虽然依赖安装失败，但项目基础结构已经生成：

# 进入项目目录
cd my-project

# 查看生成的项目结构
ls -la

第二阶段：修复文件权限

2.1 修复基础权限

# 确保在项目目录中
cd /xxx/xxx/plume-blog/my-project

# 递归修复所有文件和目录权限
chmod -R 755 .

# 特别确保 docs 目录权限正确
chmod -R 755 docs/

# 为所有 Markdown 文件设置可读权限
find . -name "*.md" -exec chmod 644 {} \;

# 验证权限
ls -la
ls -la docs/

第三阶段：Docker Compose 配置

3.1 创建 Docker Compose 文件

在项目根目录创建 docker-compose.yml：

# 创建 docker-compose.yml 文件
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  vuepress:
    image: node:20-alpine
    container_name: vuepress-blog-dev
    working_dir: /app
    volumes:
      - /xxx/xxx/plume-blog/my-project:/app
    ports:
      - "4000:8080"
    environment:
      - CI=true
    command: >
      sh -c "
        corepack enable &&
        corepack prepare pnpm@latest --activate &&
        pnpm install &&
        pnpm run docs:dev
      "
    restart: unless-stopped
    stdin_open: true
    tty: true
EOF

3.2 验证 Compose 文件

# 检查文件是否创建成功
cat docker-compose.yml

# 验证文件内容是否正确
ls -la docker-compose.yml

第四阶段：Container Manager 部署

4.1 打开 Container Manager

登录 DSM 管理界面
打开 Container Manager 应用
进入项目标签页

4.2 创建新项目

点击「新增」按钮
选择「从仓库导入」或「从 .yml 文件导入」
填写项目信息：
- 项目名称: vuepress-blog
- 描述: VuePress Theme Plume 开发环境 (可选)
- 路径: /xxx/xxx/plume-blog/my-project
- 来源：选择「文件」并指向 docker-compose.yml

4.3 启动项目

点击「下一步」完成配置验证
点击「完成」开始部署
等待项目状态变为「运行中」

第五阶段：验证部署

5.1 监控启动过程

在 Container Manager 中：

点击进入 vuepress-blog 项目
查看「日志」标签页
等待看到成功启动信息：

> sumjess@1.0.0 docs:dev /app
> vuepress dev docs

- Initializing and preparing data
✔ Initializing and preparing data - done in 2.81s

vite v7.1.12 dev server running at:
➜ Local:   http://localhost:8080/
➜ Network: http://172.17.0.5:8080/

5.2 访问博客

在浏览器中访问：

http://你的群晖IP地址:4000

第六阶段：内网穿透（cpolar）

6.1 添加你信任的、并且能控制其DNS解析的域名 (docs/.vuepress/config.ts)

  bundler: viteBundler({
    viteOptions: { // 将 viteOptions 移到这里，作为 viteBundler 的参数
      server: {
        allowedHosts: ['xxxxxxxxxxxxxxx'] // 确保这是你的 cpolar 域名
      }
    }
  }),
  shouldPrefetch: false,// 站点较大，页面数量较多时，不建议启用

🚨 重要提醒

安全考虑：allowedHosts 列表中的域名，其解析到的 IP 地址应该是你可以控制的。对于通过 cpolar 获取的临时域名，这通常是安全的。但切勿将此项随意设置为 true，因为这允许任何网站通过 DNS 重绑定攻击向你的开发服务器发送请求，可能导致源代码泄露。
重启服务：修改配置文件后，请务必重启 VuePress 的开发服务器，新的配置才能生效。

6.2 在cpolar中配置

本地地址 - 端口
其他 - 根据实际情况填写

📁 项目结构详解

my-project/
├── 📄 docker-compose.yml          # Docker 部署配置
├── 📄 package.json               # 项目依赖配置
├── 📄 pnpm-lock.yaml             # 依赖锁文件
├── 📁 docs/                      # 文档根目录
│   ├── 📁 blog/                  # 博客文章目录
│   ├── 📁 demo/                  # 示例页面目录
│   ├── 📄 README.md              # 首页内容
│   └── 📁 .vuepress/             # VuePress 配置目录
│       ├── 📄 config.ts          # 主配置文件
│       ├── 📄 plume.config.ts    # 主题配置文件
│       ├── 📄 client.ts          # 客户端增强
│       ├── 📄 collections.ts     # 内容集合配置
│       ├── 📄 navbar.ts          # 导航栏配置
│       └── 📁 public/            # 静态资源目录

⚙️ 核心配置文件说明

Docker Compose 配置解析

version: '3.8'
services:
  vuepress:
    image: node:20-alpine      # 使用 Node.js 20 Alpine 镜像
    container_name: vuepress-blog-dev  # 容器名称
    working_dir: /app          # 容器内工作目录
    volumes:
      - 宿主机项目路径:/app    # 挂载项目文件
    ports:
      - "4000:8080"           # 端口映射：宿主机:容器
    environment:
      - CI=true               # 设置非交互式环境
    command: >                # 启动命令序列
      sh -c "
        corepack enable &&    # 启用 corepack
        corepack prepare pnpm@latest --activate &&  # 激活 pnpm
        pnpm install &&       # 安装依赖
        pnpm run docs:dev     # 启动开发服务器
      "
    restart: unless-stopped   # 重启策略

VuePress 主题配置 (docs/.vuepress/config.ts)

export default defineUserConfig({
  theme: plumeTheme({
    // 博客信息配置
    profile: {
      name: "你的名称",
      avatar: "/images/avatar.jpg",
      description: "博客描述",
      // 更多配置...
    },
    // 导航栏配置
    navbar: [],
    // 集合配置
    collections: [
      { type: 'post', dir: 'blog', title: '博客' }
    ],
  }),
})

🔄 日常运维操作

启动 / 停止服务

启动：在 Container Manager 中点击项目「启动」
停止：点击项目「停止」
重启：点击项目「重启」

查看日志

# 通过命令行查看日志
docker logs vuepress-blog-dev

# 实时查看日志
docker logs -f vuepress-blog-dev

更新项目

当修改项目文件后，服务会自动热重载。如需完全重启：

# 重启容器
docker restart vuepress-blog-dev

🛠️ 故障排除指南

问题 1: 端口冲突

症状: 容器启动失败，日志显示 address already in use

解决方案:

# 修改 docker-compose.yml 中的端口映射
ports:
  - "4001:8080"  # 改为其他可用端口

问题 2: 权限错误

症状: EACCES 或文件访问被拒绝

解决方案:

# 修复文件权限
chmod -R 755 /xxx/xxx/plume-blog/my-project

问题 3: 依赖安装失败

症状: Segmentation fault 或安装过程中断

解决方案:

# 进入容器手动安装
docker exec -it vuepress-blog-dev sh
cd /app
pnpm install
exit

✅ 部署完成验证清单

项目基础结构创建成功
文件权限正确设置
Docker Compose 文件配置完成
Container Manager 项目部署成功
容器状态显示「运行中」
日志显示 VuePress 启动成功
通过浏览器正常访问博客
文件修改能够热重载

💡 使用技巧

快速重启：修改配置后无需重启容器，VuePress 会自动热重载
文件编辑：直接在宿主机编辑文件，更改实时生效
备份策略：定期备份 docs/blog/ 和配置文件
版本控制：建议将项目加入 Git 版本控制

版权所有

版权归属：sumjess

许可证：署名 4.0 国际 (CC-BY-4.0)