互联网折腾日记

Astro 博客安装、目录布局与 Fuwari 主题接入记录

Thu, 02 Apr 2026 00:00:00 GMT

今天把本地博客从一个最小可用的 Astro 版本，整理成了适合正式部署的结构，并进一步切换到了 Fuwari 主题。整个过程的重点不只是把页面跑起来，而是把目录、构建方式和后续写作方式一起固定下来，这样后面维护会轻松很多。

这次最终采用的方案

现在的博客结构可以概括成三层：

用 Astro 负责内容组织和静态页面生成。
用 Fuwari 提供博客主题、归档、搜索、RSS 和整体样式。
用 Docker Compose + Nginx 作为生产部署方式。

这样拆开的好处是很明确的。Astro 负责生成静态文件，Nginx 只负责托管这些静态文件，运行时足够简单；而主题层则由 Fuwari 提供，不需要自己从零写页面结构。

现在的目录布局

当前最重要的目录是这些：

WechatWorkspace/
├── astro-blog/
│   ├── src/
│   │   ├── content/
│   │   │   ├── posts/
│   │   │   └── spec/
│   │   ├── components/
│   │   ├── layouts/
│   │   ├── pages/
│   │   └── config.ts
│   ├── public/
│   ├── Dockerfile
│   ├── Dockerfile.dev
│   ├── astro.config.mjs
│   ├── package.json
│   └── pnpm-lock.yaml
├── docker-compose.yml
└── docker-compose.dev.yml

这里面最关键的是：

astro-blog/src/content/posts/ 以后新文章都放这里。
astro-blog/src/config.ts 管站点标题、简介、头像、导航栏和主题色。
docker-compose.yml 生产版启动方式。
docker-compose.dev.yml 开发预览方式。

这次安装和改造的流程

1. 先搭一个最小 Astro 博客

一开始先做的是一个很轻的 Astro 站点，只需要文章列表页和文章详情页，目的是先确认现有 Markdown 能正常导入和阅读。

当时的重点不是主题，而是验证两件事：

现有 Markdown 能不能顺利迁进去。
Docker Compose 在本地能不能稳定跑起来。

这样做的好处是，先把内容迁移链路打通，再换主题，问题会少很多。

2. 再切成生产版部署结构

确认内容能跑以后，把部署方式改成了正式一点的模式：

构建阶段使用 Node 容器执行 astro build
输出 dist/
Nginx 镜像只负责托管 dist/

对应思路就是典型的多阶段构建：

FROM node:20-alpine AS builder
# 安装依赖并构建 dist

FROM nginx:1.27-alpine
# 复制 dist 到 nginx html 目录

这种方式比直接跑 astro dev 更适合服务器，因为：

运行时更轻
暴露面更小
没有开发服务器依赖
更接近静态站的标准部署方式

3. 最后切到 Fuwari 主题

后面把博客模板层整体替换成了 Fuwari。

要注意的是，Fuwari 不是简单的“换一套 CSS”，它本身就是一套完整的 Astro 博客模板，包含：

自己的内容 schema
自己的路由结构
搜索功能
RSS
归档页
关于页
主题配置

所以这一步的正确做法不是零碎拼接，而是：

用 Fuwari 作为新的模板底座。
把原来的文章内容迁移到它的 src/content/posts/。
按它要求的 frontmatter 改字段。
再把 Docker/Nginx 生产构建接回去。

文章格式现在怎么写

现在文章不是随便一个 Markdown 就能直接识别，必须符合 Fuwari 的 frontmatter 格式。

最常用的最小模板是：

---
title: 文章标题
published: 2026-04-02
description: 一句话描述文章内容
tags: [Astro, Docker]
category: 建站
draft: false
---

这里开始写正文。

注意几个字段：

title 文章标题。
published 发布时间。
description 首页和 SEO 描述常用。
tags 标签列表。
category 分类。
draft 如果写成 true，生产构建时通常不会出现在正式页面里。

以后文章放哪里

以后新文章统一放在：

astro-blog/src/content/posts/

比如你写一篇：

astro-blog/src/content/posts/astro-notes.md

最终路径会是：

/posts/astro-notes/

如果你放在子目录里，例如：

astro-blog/src/content/posts/docker/nginx.md

那路径就会变成：

/posts/docker/nginx/

本地预览和生产预览

这次也顺手把开发和生产两种运行方式分开了。

开发模式

开发时更适合用：

docker compose -f docker-compose.dev.yml up --build -d

它启动的是 Astro 开发服务器，适合边改边看。

生产模式

正式预览或准备上线时用：

docker compose up --build -d

它会：

执行 pnpm build
生成静态文件
用 Nginx 对外提供服务

这次踩到的一个小问题

切到 Fuwari 之后，开始时首页里多出了一篇主题自带的演示文章。这个问题不是构建错误，而是因为主题仓库里还有一个默认示例内容目录没有清掉。

这类问题很典型，也提醒了一点：

换主题时，除了看 src/content/posts/*.md
也要检查有没有 src/content/posts/**/index.md 这种子目录文章

否则你以为自己只保留了 4 篇文章，结果页面上还会冒出主题自带的内容。

Astro 的几个实用小技巧

1. 先把内容链路打通，再折腾主题

如果一开始就同时换主题、改部署、迁内容，问题会缠在一起。更稳的顺序是：

先用最小 Astro 站点确认 Markdown 能正常显示
再确定生产部署方式
最后再替换成正式主题

这样定位问题非常快。

2. 静态博客尽量用生产构建验证

开发模式只是方便写作，真正决定是否能上线的是生产构建能不能成功。

所以每次改完结构、依赖或主题，最好都跑一次：

docker compose up --build -d

只要生产构建能过，基本就说明这次改动是可部署的。

3. frontmatter 要尽量固定

静态博客最怕的不是页面丑，而是文章格式今天一个样、明天一个样。后面一旦多了十几篇、几十篇，就很难统一整理。

比较稳的方法是从一开始就固定模板，例如：

标题
发布时间
描述
标签
分类
draft 状态

这样后面自动生成归档、搜索和 RSS 都会更稳定。

4. 主题仓库不要直接当成“黑盒”

像 Fuwari 这种主题本质上是完整项目，不是一个单独样式包。所以接入前最好先确认：

package.json
src/content/config.ts
src/config.ts
src/pages/

这四类文件基本决定了：

依赖怎么装
文章字段怎么写
站点信息在哪改
页面路由怎么组织

5. 写博客时把“部署信息”也记进文章

今天这次迁移里最有价值的部分之一，其实不是主题，而是把部署方式也固定进了代码结构。

比如：

开发版 Compose
生产版 Compose
Dockerfile
Nginx 配置

以后就算隔一段时间不碰这个博客，回来时也能很快接上。

这套结构接下来怎么用

后面写文章时，流程可以很简单：

在 astro-blog/src/content/posts/ 新建一个 .md
按固定 frontmatter 填好标题、日期、描述和标签
写正文
本地预览
确认没问题后提交 Git

如果只是写内容，基本不需要再碰页面结构；只有在想改主题风格、导航、SEO 或部署方式时，才需要去动模板层和配置层。

小结

今天这次整理，真正完成的不是“把博客装上”，而是把一套长期可维护的博客工作流定下来了：

内容放哪里
主题怎么接
Docker 怎么跑
Nginx 怎么托管
Git 怎么留版本切换点

后面无论继续用 Fuwari，还是再换别的 Astro 主题，都已经有了一个比较稳的基础。

新服务器配置记录

Tue, 31 Mar 2026 00:00:00 GMT

服务器信息

IP: ${ip}
系统: Ubuntu 24.04.2 LTS
内核: 6.8.0-63-generic

服务访问地址

Dockge: http://${ip}:5001

配置步骤

1. 系统更新

apt update

2. SSH 免密码登录配置

2.1 创建 .ssh 目录并设置权限

mkdir -p ~/.ssh
chmod 700 ~/.ssh

2.2 添加 Mac Mini 公钥到 authorized_keys

echo 'ssh-ed25519 ${key} Mac Mini' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

2.3 验证 SSH 配置

cat ~/.ssh/authorized_keys

2.4 测试免密码登录

从 Mac Mini 执行：

ssh root@${ip}

ZeroTier

安装并启动：

curl -s https://install.zerotier.com | bash
systemctl enable --now zerotier-one

加入网络：

zerotier-cli join ${networkId}

检查状态：

zerotier-cli info
zerotier-cli listnetworks

当前记录：

ZeroTier 版本：1.16.1
节点 ID：${moonId}
网络 ID：${networkId}
当前状态：REQUESTING_CONFIGURATION
服务状态：ONLINE
Moon ID：000000${moonId}
Moon 稳定端点：${ip}/9993

说明：

REQUESTING_CONFIGURATION 表示已经成功发起入网请求。
还需要在 ZeroTier Central 或控制器中授权节点 ${moonId}，授权后才会分配虚拟 IP。
当前服务器已经可作为 Moon 节点被其他客户端 orbit。

ZeroTier Moon

客户端接入 Moon：

zerotier-cli orbit ${moonId} ${moonId}
zerotier-cli listmoons

服务器验证：

zerotier-cli listmoons
zerotier-cli info
ss -lunp | grep 9993

当前记录：

zerotier-cli listmoons 已返回本机 Moon 信息
Moon 稳定端点：${ip}/9993
zerotier-one 服务状态：active

外部检查项：

云安全组需要放行 UDP 9993
如果云侧未放行，即使本机服务正常监听，外部节点仍然无法通过 Moon 建立连接

Dockge

mkdir -p /root/docker/dockage

编排文件： /root/docker/dockage/docker-compose.yml

内容如下：

services:
  dockge:
    image: louislam/dockge:1
    container_name: dockge
    restart: always
    ports:
      - "5001:5001"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
      - /root/docker:/root/docker
    environment:
      - DOCKGE_STACKS_DIR=/root/docker

启动命令：

cd /root/docker/dockage
docker compose up -d
docker compose ps

停止 / 重启：

cd /root/docker/dockage
docker compose stop
docker compose restart

访问地址： http://${ip}:5001

当前记录：

容器名：dockge
镜像：louislam/dockge:1
端口映射：5001:5001

补充说明：

Dockge 使用宿主机目录 /root/docker 作为 stack 目录。
Dockge 数据目录为 /root/data/dockge。

Codex CLI

安装前检查：

command -v node
command -v npm
command -v codex

安装命令：

apt-get update
apt-get install -y nodejs npm
npm i -g @openai/codex

验证命令：

node -v
npm -v
which codex
codex -V

当前记录：

Node.js 版本：v18.19.1
npm 版本：9.2.0
Codex CLI 版本：0.117.0
Codex 路径：/usr/local/bin/codex
全局 npm 模块目录：/usr/local/lib/node_modules
npm 包：@openai/codex@0.117.0

登录方式：

codex login --device-auth

常用命令

ZeroTier

zerotier-cli info
zerotier-cli listnetworks
zerotier-cli listmoons
zerotier-cli orbit ${moonId} ${moonId}