<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>https://www.l3thargy.cn/</id>
  <title type="text">L3thargy-Blog</title>
  <subtitle type="text">一个基于 Astro 框架和 Firefly 模板的个人博客</subtitle>
  <updated>2026-11-19T19:33:11.000Z</updated>
  <author><name>L3thargy</name></author>
  <link rel="alternate" href="https://www.l3thargy.cn/"/>
  <link rel="self" href="https://www.l3thargy.cn/atom.xml"/>
  <generator uri="https://github.com/CuteLeaf/Firefly">Firefly v6.16.9</generator>
    <entry>
      <id>https://www.l3thargy.cn/posts/building-blog-admin/</id>
      <title type="text">我给我的博客做了一个后台</title>
      <published>2026-11-19T19:33:11.000Z</published>
      <updated>2026-11-19T19:33:11.000Z</updated>
      <author><name>L3thargy</name></author>
      <link rel="alternate" href="https://www.l3thargy.cn/posts/building-blog-admin/"/>
      <summary type="text"></summary>
      <content type="html"><![CDATA[<section><h1>从零给个人博客写一个管理后台：技术选型、一键启动与云端部署<a href="#从零给个人博客写一个管理后台技术选型一键启动与云端部署"><span>#</span></a></h1><blockquote><p>部署上线那天，后台登录正常、文章列表正常，唯独正文编辑区一片空白。
这篇文章记录了从选型到上线的全过程，以及四个真正花掉时间的坑。</p></blockquote><section><h2>一、为什么自己写<a href="#一为什么自己写"><span>#</span></a></h2><p>我的博客是纯 Markdown 驱动的静态站，文章就是服务器上的一个个 <code>.md</code> 文件，发布靠 Git。市面上现成的后台，大多围绕 Cloudflare 全家桶设计——用 Pages 部署、用 D1 存数据，这套方案在国内访问不稳定，日常管理也别扭；剩下的基本都要绑定传统数据库，导出的内容还和我的目录结构对不上，改造成本比从零写还高。</p><p>说到底，我想要的是一个不依赖任何外部平台、数据始终留在自己服务器和 Git 仓库里的后台。</p><p>需求其实很收敛：</p><ul>
<li>文章、页面、项目的增删改查</li>
<li>Markdown 编辑，支持图片上传</li>
<li>一键 Git 提交发布</li>
<li>首次访问的初始化引导和登录鉴权</li>
<li>部署在我自己的服务器上，不依赖第三方</li>
</ul><p>那就自己写。</p></section><section><h2>二、整体结构<a href="#二整体结构"><span>#</span></a></h2><div><figure><figcaption></figcaption><pre><code><div><div><div>1</div></div><div><span>访客 ──HTTPS──▶ 腾讯云 EdgeOne（静态托管 + CDN）</span></div></div><div><div><div>2</div></div><div><span><span>                  </span></span><span>└─ 博客构建产物（HTML / CSS / JS）</span></div></div><div><div><div>3</div></div><div>
</div></div><div><div><div>4</div></div><div><span>我 ──HTTPS──▶ admin.example.com</span></div></div><div><div><div>5</div></div><div><span><span>                 </span></span><span>└─ 腾讯云轻量应用服务器</span></div></div><div><div><div>6</div></div><div><span><span>                      </span></span><span>└─ Nginx ──▶ Fastify (127.0.0.1:5175)</span></div></div><div><div><div>7</div></div><div><span><span>                                     </span></span><span>├─ /admin/   管理前端（Vue SPA）</span></div></div><div><div><div>8</div></div><div><span><span>                                     </span></span><span>├─ /api/     管理接口</span></div></div><div><div><div>9</div></div><div><span><span>                                     </span></span><span>└─ 本地仓库    Markdown 文件 + Git 发布</span></div></div></code></pre><div><div></div><div></div></div></figure></div><p>实际部署是拆成两块的。博客本身是纯静态站，交给腾讯云 EdgeOne 托管：构建产物传上去就有 CDN 加速和自动 HTTPS，国内访问速度也稳。后台则需要一个能长期跑 Node 进程、读写本地文件的环境，所以放在一台腾讯云轻量应用服务器上，用独立的二级域名访问，Nginx 反代到 Fastify。</p><p>这样拆分的好处是互不打扰：博客出问题不影响后台发布，后台重启也不影响读者访问；管理端不暴露在主站域名下，攻击面更小；文章的源文件始终留在自己服务器的 Git 仓库里。</p><p>一个关键决定：<strong>前后端同源</strong>。Fastify 同时提供 <code>/admin/</code> 静态资源和 <code>/api/</code> 接口，Nginx 只做一层反向代理。这样省掉了 CORS 配置，Cookie 也是天然的 SameSite，鉴权链路干净很多。</p><p>技术栈：</p>

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