手把手教程：使用Docker快速部署轻量级Markdown博客PaperGrid

April 4, 2026

在之前的文章中，我们介绍过如何使用 Halo 2.0 搭建功能全面的个人博客。不过，对于很多朋友来说，这类平台虽然强大，但架构相对复杂，维护起来也需要一定精力。如果你和我一样，更偏爱那种简洁、轻快、专注于内容本身的博客系统，那么今天分享的 PaperGrid 或许正合你意。

PaperGrid 是一个新兴的轻量化博客项目，它基于现代技术栈构建，界面设计清新优雅，对 Markdown 的支持非常友好，并且自带完善的后台管理系统。更重要的是，它的部署过程非常简单，尤其适合在 NAS 或云服务器上快速搭建。接下来，我就以威联通（QNAP）NAS 为例，带你一步步用 Docker Compose 部署 PaperGrid，并分享一些初步的使用体验。

对我个人而言，博客已经不仅仅是分享平台，它更像是一个数字化的思考工具箱。把技术实践、学习心得甚至生活灵感记录下来，既能帮助自己梳理思路，也能与志同道合的人交流。像 PaperGrid 这样轻便又好看的系统，正好为打造这样一个私人知识空间提供了理想的基础。

初识 PaperGrid：轻量，但不简单

你可以在 GitHub 上搜索完整项目名：xywml/PaperGrid。

PaperGrid 是一个基于 Next.js App Router 构建的个人博客与后台管理系统。它虽然定位轻量，但该有的功能一个不少：用户认证、文章管理、评论系统、多语言支持、深色模式，甚至内置了多套可一键切换的前端主题。作者在项目说明中提到，目前项目仍处于快速迭代阶段，欢迎大家部署使用并反馈建议。

核心功能一览

现代技术栈：基于 Next.js App Router 与 React 19 开发，性能与开发体验俱佳。
数据管理：使用 Prisma ORM 处理数据库操作，代码清晰且类型安全。
安全认证：集成 NextAuth，提供可靠的用户登录与权限管理。
完整后台：拥有文章、标签、分类、评论、用户、系统设置及文件管理的可视化后台。
便捷的文件管理：支持本地图片上传、预览、删除，并可将图片 URL 自动插入编辑器。
强大的内容支持：完美支持 MDX，具备代码高亮、数学公式渲染（KaTeX）与图表（Mermaid）绘制能力。
国际化与主题：支持中英文切换，并内置深色/浅色模式。
多样前端主题：管理员可在后台“样式”设置中一键切换多套精心设计的前台主题（如“纸格笔记”、“终端机能”、“清透视窗”等）。
扩展潜能：架构预留了集成 AI 助手等智能功能的接口，未来可玩性很高。

详细部署步骤（以威联通 NAS 为例）

我们将使用 Docker Compose 来部署 PaperGrid，这种方式配置清晰、管理方便。下面的 docker-compose.yml 配置已经包含了运行所需的核心环境变量，你只需要根据自己网络环境稍作调整即可。

创建一个新的 docker-compose.yml 文件，并粘贴以下内容：

services:
  papergrid:
    image: ghcr.io/xywml/papergrid:latest
    container_name: papergrid
    ports:
      - "6066:3000" # 将容器内的3000端口映射到主机的6066端口
    environment:
      DATABASE_URL: "file:/data/db.sqlite"
      # 可选：为 AI 向量索引使用单独的 SQLite 文件
      # AI_VECTOR_DATABASE_URL: "file:/data/ai-index.sqlite"
      # SQLITE_JOURNAL_MODE: "DELETE"

      # 重要：此处填写你访问博客的地址。初期用NAS IP+端口，后期配置了域名再改。
      NEXTAUTH_URL: "http://192.168.100.138:6066"
      NEXT_PUBLIC_APP_URL: "http://192.168.100.138:6066"

      # 生产环境务必设置一个足够长且复杂的随机字符串
      NEXTAUTH_SECRET: "请替换成一串足够长的随机字符串"

      # 设置本地媒体文件与Next.js缓存存储路径
      MEDIA_ROOT: "/data/uploads"
      NEXT_CACHE_DIR: "/data/.next-cache"

      # 首次初始化容器时的可选配置（用于创建管理员）
      # INIT_ADMIN_TOKEN: "请替换为随机字符串"
      # ADMIN_INIT_PASSWORD: "请替换为强密码"

      # 可先跳过 OAuth / SMTP 等高级配置，待基础服务运行后再补充
      NEXT_PUBLIC_DEFAULT_LOCALE: "zh"
      # 在内网环境且未配置反向代理时，允许信任 Host 头
      AUTH_TRUST_HOST: "true"

    volumes:
      - /share/Container/boke/data:/data # 请将此路径修改为你NAS上准备存储数据的目录

    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "5"

配置说明与调整要点：

NEXTAUTH_URL 与 NEXT_PUBLIC_APP_URL：请将 192.168.100.138 替换为你 NAS 的实际内网 IP 地址。
NEXTAUTH_SECRET：这是关键的安全密钥。请务必使用一个强随机字符串生成工具（如 openssl rand -base64 32）生成并替换。
volumes 映射：/share/Container/boke/data 是示例路径，你需要将其改为 NAS 上你希望持久化存储数据库、上传文件和缓存的真实目录。

可选：使用 `.env` 文件管理配置

如果你觉得在 Compose 文件里写环境变量太长，也可以选择创建一个独立的 .env 文件。PaperGrid 支持丰富的配置项，以下是完整的参考列表，你可以将需要修改的部分保存为 .env 文件，与 docker-compose.yml 放在同一目录，并在 Compose 文件中通过 env_file 指令引入。

DATABASE_URL="file:./dev.db"
# 可选：为 AI 向量索引单独使用 SQLite 文件（推荐生产启用）
# AI_VECTOR_DATABASE_URL="file:/data/ai-index.sqlite"
# 可选：AI 向量索引使用的 SQLite 日志模式；默认 DELETE（稳定优先）
# SQLITE_JOURNAL_MODE="DELETE"

NEXTAUTH_URL="http://localhost:6066"
NEXTAUTH_SECRET="your-secret-key-change-this-in-production"

# 本地媒体存储设置
MEDIA_ROOT="/data/uploads"
MEDIA_MAX_UPLOAD_MB="10"
MEDIA_MAX_INPUT_PIXELS="40000000"
MEDIA_RESOLVE_CACHE_TTL_MS="30000" # 媒体元数据缓存(毫秒)
INIT_ADMIN_TOKEN=""
ADMIN_INIT_PASSWORD=""

# 第三方 OAuth 登录配置（如 GitHub, Google）
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

# 云存储配置（如 Cloudinary）
CLOUDINARY_CLOUD_NAME=""
CLOUDINARY_API_KEY=""
CLOUDINARY_API_SECRET=""

# 邮件服务器配置（用于通知等功能）
SMTP_HOST=""
SMTP_PORT="465"
SMTP_SECURE="true"
SMTP_USER=""
SMTP_PASS=""
# 可选：指定收件人，多个用逗号分隔；留空则发送给所有管理员
EMAIL_TO=""
# 可选：回复通知邮件的拒收名单
EMAIL_REPLY_DENYLIST=""
# 可选：退订链接签名密钥（不填则回退到 NEXTAUTH_SECRET）
EMAIL_UNSUBSCRIBE_SECRET=""
# 可选：退订链接有效期（天）
EMAIL_REPLY_UNSUBSCRIBE_EXPIRE_DAYS="365"

# Gotify 推送配置
GOTIFY_URL=""
GOTIFY_TOKEN=""

NEXT_PUBLIC_APP_URL="http://localhost:6066"
NEXT_PUBLIC_DEFAULT_LOCALE="zh"
# 可选：设置日志级别
# LOG_LEVEL="info"

# 自定义 Head 注入与 CSP 安全策略
# 在管理后台「样式 → 自定义 Head 注入」添加外部脚本后，需将脚本域名加入此处
# HEAD_INJECT_SCRIPT_ORIGINS="https://stats.example.com,https://www.googletagmanager.com"
# 可选：关闭 script-src 'unsafe-inline'（默认保留以兼容旧部署）
# CSP_ALLOW_UNSAFE_INLINE_SCRIPT="false"