手把手教程:使用Docker快速部署轻量级Markdown博客PaperGrid
在之前的文章中,我们介绍过如何使用 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"
在威联通 Container Station 中部署
- 打开威联通 NAS 上的 Container Station 应用。
- 点击“创建” -> “创建应用程序”。
- 在编辑窗口中,清空默认内容,将上面调整好的
docker-compose.yml配置全文粘贴进去。 - 点击“创建”即可。Container Station 会自动拉取镜像并启动服务。

等待片刻,当容器状态显示为“运行中”时,部署就完成了。
初体验:登录、写作与后台管理
部署成功后,打开浏览器,访问 http://你的NAS_IP:6066,就能看到 PaperGrid 简洁优雅的前台界面了。

1. 登录后台
点击页面右上角的“登录”按钮,进入登录界面。系统默认的管理员账号为:
- 邮箱:
admin@example.com - 密码:
admin123
安全提醒:首次登录后,请务必立即在后台的“用户”设置中修改这个默认密码。

2. 开始写作
进入后台,点击“文章”->“新建”,即可开始创作。PaperGrid 内置的编辑器给我留下了深刻印象——它响应迅速,Markdown 预览实时同步,图片上传拖拽即可完成,体验甚至比我目前用的某些大型博客平台还要流畅。

编辑器完美支持 MDX、代码块、表格、数学公式等高级格式,完全能满足技术写作的需求。

3. 探索后台与个性化
PaperGrid 的后台功能相当丰富。你可以在“系统设置”中配置站点信息,在“样式”里一键切换多种前台主题,瞬间改变博客的整体风格。此外,用户管理、评论审核、文件库等功能也都井然有序,DIY 的自由度很高。

总结:它适合你吗?
总的来说,PaperGrid 精准地命中了一个细分需求:它不像 WordPress 或 Halo 那样“大而全”,但避免了随之而来的复杂性和资源占用;同时,它又提供了远超静态博客生成器的交互功能和管理便利性。
它非常适合以下场景:
- 追求快速、轻量部署,希望把更多精力放在写作本身。
- 习惯使用 Markdown,并需要代码高亮、公式等技术支持。
- 希望拥有一定的定制权(如切换主题、管理评论),但又不想折腾底层代码。
- 想在 NAS、树莓派或低配置 VPS 上搭建一个美观实用的个人博客或知识库。
如果你正寻找一个简洁现代、易于上手且不乏深度的博客系统,PaperGrid 绝对是一个值得你花半小时尝试的出色选择。希望这篇详细的部署指南能帮你顺利搭建起属于自己的写作空间。