我给我的博客做了一个后台
从零给个人博客写一个管理后台:技术选型、一键启动与云端部署
部署上线那天,后台登录正常、文章列表正常,唯独正文编辑区一片空白。 这篇文章记录了从选型到上线的全过程,以及四个真正花掉时间的坑。
一、为什么自己写
我的博客是纯 Markdown 驱动的静态站,文章就是服务器上的一个个 .md 文件,发布靠 Git。市面上现成的后台,大多围绕 Cloudflare 全家桶设计——用 Pages 部署、用 D1 存数据,这套方案在国内访问不稳定,日常管理也别扭;剩下的基本都要绑定传统数据库,导出的内容还和我的目录结构对不上,改造成本比从零写还高。
说到底,我想要的是一个不依赖任何外部平台、数据始终留在自己服务器和 Git 仓库里的后台。
需求其实很收敛:
- 文章、页面、项目的增删改查
- Markdown 编辑,支持图片上传
- 一键 Git 提交发布
- 首次访问的初始化引导和登录鉴权
- 部署在我自己的服务器上,不依赖第三方
那就自己写。
二、整体结构
访客 ──HTTPS──▶ 腾讯云 EdgeOne(静态托管 + CDN) └─ 博客构建产物(HTML / CSS / JS)
我 ──HTTPS──▶ admin.example.com └─ 腾讯云轻量应用服务器 └─ Nginx ──▶ Fastify (127.0.0.1:5175) ├─ /admin/ 管理前端(Vue SPA) ├─ /api/ 管理接口 └─ 本地仓库 Markdown 文件 + Git 发布实际部署是拆成两块的。博客本身是纯静态站,交给腾讯云 EdgeOne 托管:构建产物传上去就有 CDN 加速和自动 HTTPS,国内访问速度也稳。后台则需要一个能长期跑 Node 进程、读写本地文件的环境,所以放在一台腾讯云轻量应用服务器上,用独立的二级域名访问,Nginx 反代到 Fastify。
这样拆分的好处是互不打扰:博客出问题不影响后台发布,后台重启也不影响读者访问;管理端不暴露在主站域名下,攻击面更小;文章的源文件始终留在自己服务器的 Git 仓库里。
一个关键决定:前后端同源。Fastify 同时提供 /admin/ 静态资源和 /api/ 接口,Nginx 只做一层反向代理。这样省掉了 CORS 配置,Cookie 也是天然的 SameSite,鉴权链路干净很多。
技术栈:
| 层 | 选型 |
|---|---|
| 前端 | Vue 3.5 + TypeScript + Vite 8 + Element Plus |
| 编辑器 | Vditor(Markdown,IR / 所见即所得 / 源码三模式) |
| 后端 | Fastify 5 + Zod 4 |
| 图片处理 | sharp |
| 工程 | npm workspaces(web / server 两个包) |
前端构建的 base 固定为 /admin/,这样后台可以挂在独立域名的子路径下,静态资源和接口也天然同源。
三、关键设计一:让人双击就能跑
这是我花时间最多、也最值得的一块。目标很朴素:拿到项目的人,双击 start.bat(或执行 ./start.sh)就能用,不需要先看文档装环境。
脚本自动完成四件事:检测 Node.js ≥ 22、检测 Git、安装依赖并构建、检查端口后启动并打开浏览器。环境缺失时自动补:Node 从 npmmirror、华为云、清华、官方四个镜像依次尝试,并用 SHASUMS256.txt 校验;Git 在 Windows 上装 PortableGit 到项目内的 .runtime/git,Linux 走 apt / dnf / yum / apk / pacman。
坑基本都在 Windows 批处理上:文件必须 CRLF、消息只用 ASCII、流程用 goto :label 组织;另外 choice /C YN 之后 if errorlevel 2 代表选了 N,和直觉相反。这些规则写进了 .gitattributes:
* text=auto*.bat text eol=crlf*.sh text eol=lf四、关键设计二:构建与发布链路
本地开发和生产部署是两条路径,中间需要一个稳定的交付物。
build-release.mjs 负责产出一个自包含目录:
release/firefly-admin-0.1.0/├── server/dist/ # 后端编译产物├── web/dist/ # 前端构建产物(含 Vditor 静态资源)├── scripts/ # 安装脚本├── package.json # 只含生产依赖├── start.bat / start.sh└── .env.examplebuild-upload.bat / build-upload.sh 再把它打成 zip 方便上传。Windows 用系统自带的 tar -a -c -f,Unix 用 zip,不额外引入打包依赖。
这里有一个非常典型的坑:生产依赖边界。
后台在服务器上启动时报:
ERR_MODULE_NOT_FOUND: Cannot find package 'esbuild'原因是 esbuild 被放在了 devDependencies,但服务端代码在运行时静态 import 了它。本地 npm install 会装全部依赖,一切正常;服务器执行 npm install --omit=dev 之后,它就消失了。
修法只有一步——把它移进 dependencies:
"dependencies": { "esbuild": "^0.28.2", "fastify": "^5.12.8", "sharp": "^0.35.5"}但真正的经验是验证方式:不要只在开发环境验证部署包。把 release 目录复制到临时目录,执行
npm install --omit=devnode server/dist/index.js跑通才算完成。这个动作后来成了每次改依赖后的固定步骤。
五、关键设计三:CSRF 与反向代理
后台的写操作接口做了同源校验:取 Origin(或 Referer)里的 host,和请求头里的 Host 严格比较,不一致直接 403。本地开发一切正常,部署到服务器、配好 HTTPS 之后,登录接口却稳定返回 403。
原因出在 Nginx 配置:
proxy_set_header Host $host:$server_port;HTTPS 下 $server_port 是 443,后端收到的 Host 是 admin.example.com:443,而 Origin 里的 host 没有端口,字符串自然不相等。改成原样透传:
proxy_set_header Host $http_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;$http_host 就是浏览器发来的原始 Host,带不带端口都与 Origin 完全一致。注意也不要用 $host——它在非标准端口访问时会丢端口,同样会踩坑。
六、部署实录:EdgeOne + 轻量服务器
域名拆成两个:博客主站走 EdgeOne,后台用独立二级域名指向轻量应用服务器。两边的部署都很轻。
博客主站:本地构建出静态文件,上传到 EdgeOne 的静态托管,绑定主域名即可。CDN 加速、HTTPS 证书、缓存策略都由平台负责,服务器完全不用承担访问流量。
后台服务:轻量服务器上装宝塔面板,Node 项目指向后台目录,部署流程比想象中简单,但每一步都有细节。
启动命令:宝塔的 Node 项目默认启动方式可能解析不出命令,报 nohup: failed to run command 'False'。直接用自定义命令 node server/dist/index.js,或者用 PM2 托管,都能解决。
反向代理:站点配置里把 / 代理到 127.0.0.1:5175,按上一节的四个 proxy_set_header 配好。
HTTPS:证书部署本身没问题,但要注意两件事。一是云厂商安全组的 443 入站规则,二是宝塔防火墙的 443 放行——缺任何一个,浏览器都是 ERR_CONNECTION_TIMED_OUT,和证书无关。判断方法很简单:Test-NetConnection 域名 -Port 443,TCP 不通就是网络层,别去翻证书配置。
环境变量:.env 在启动时自动加载,PORT、COOKIE_SECURE 这些都在里面。上了 HTTPS 之后记得把 COOKIE_SECURE 打开。
七、踩坑清单
1. Vite 把静态资源当模块解析
模板里直接写 <img src="/admin/favicon.svg">,构建报 Module not found。改用 %BASE_URL% 和 import.meta.env.BASE_URL 拼路径即可。
2. devDependencies 里的运行时依赖
见第四节。判断标准只有一条:代码里有没有 import 它。
3. Nginx 给 Host 加了默认端口
见第五节。反向代理一律用 $http_host。
4. 一个 .gitignore 规则让编辑器消失
这是最后一个、也是最隐蔽的坑。
上线后打开文章编辑页,「正文」区域一片空白,没有工具栏,也没有报错弹窗。
编辑器是 Vditor,它需要从 /admin/vditor/... 加载自己的 i18n、语法高亮、lute 等资源。直接在浏览器打开那个核心脚本的地址:
https://admin.example.com/admin/vditor/dist/js/lute/lute.min.js看到的却是后台自己的「页面不存在」——因为服务端对所有未知的 /admin/* GET 请求都会返回 index.html 做 SPA 兜底。脚本请求拿到一段 HTML,解析失败,编辑器容器就一直空着。
资源为什么不在?继续查仓库:
git check-ignore -v web/public/vditor/dist/js/lute/lute.min.js# .gitignore:2:dist/ web/public/vditor/dist/js/lute/lute.min.js.gitignore 里的 dist/ 没有前导斜杠,会匹配任意层级的 dist 目录,把 web/public/vditor/dist/ 整个吞掉了。于是这批静态资源从未进入 Git,从仓库拉下来构建的包自然没有编辑器。
修法是锚定路径:
node_modules//web/dist//server/dist//release/同时在构建脚本里加一道校验,缺资源就中止构建:
try { await fs.access(path.join(root, "web/dist/vditor/dist/js/lute/lute.min.js"));} catch { throw new Error("缺少 Vditor 静态资源:请确认 web/public/vditor 完整后重新构建");}八、可以带走的几条结论
- 反向代理透传 Host,用
$http_host,别用$host:$server_port - 运行时
import的包,一律放dependencies;部署包必须用--omit=dev实测 .gitignore里的目录规则要加前导斜杠,否则会误伤深层同名目录- SPA 兜底会掩盖静态资源的 404,排查时先看返回体是不是 HTML
- 构建产物要加断言,让缺资源在构建期暴露,而不是上线后
九、开源与使用
项目已经开源:Firefly Admin Console。
三种启动方式:
- 本地一键:Windows 双击
start.bat,macOS / Linux 执行./start.sh - 构建上传:运行
build-upload.bat或./build-upload.sh,产出可直接上传的 zip - 服务器手动:解压后
npm install --omit=dev,node server/dist/index.js
仓库地址:https://gitee.com/L3thargy/firefly-admin-console (顺手点个 Star 就更好了。)
如果你也在给自己的博客写后台,希望这几个坑能帮你省掉一个晚上。
文章分享
如果这篇文章对你有帮助,欢迎分享给更多人!














