personal-homepage

一个基于 Astro 的个人主页项目，定位为：

静态站点 + 构建时数据同步层

运行时对外提供纯静态页面；构建阶段由脚本从 Gitea / Seafile 拉取数据，生成本地 JSON，再交给 Astro 渲染。

当前能力

• Astro 静态站点
• Markdown 日志内容
• 项目 / 分享 / Gitea 活动页
• 构建时同步 Gitea / Seafile 数据
• 部署前按清单同步静态图片资源
• generated JSON schema 校验
• 统一重建入口 npm run rebuild
• 结构化错误码与 REBUILD_RESULT 输出，便于 AstrBot / cron 调用

快速开始

1. 安装依赖

npm install

2. 配置环境变量

复制示例文件：

cp .env.example .env

然后填写：

• PUBLIC_SITE_URL
• PUBLIC_GITEA_URL
• PUBLIC_GITHUB_URL
• PUBLIC_BLOG_URL
• PUBLIC_GITEA_USERNAME
• GITEA_BASE_URL
• GITEA_TOKEN
• GITEA_USERNAME
• SEAFILE_BASE_URL
• SEAFILE_TOKEN

如果某些远端还没接好，也可以先保留为空；系统会按当前策略回退到 seed data。 如果正式域名还没下来，PUBLIC_SITE_URL / PUBLIC_BLOG_URL 也可以先留空。

3. 本地开发

npm run dev

4. 手动同步内容

npm run content:sync

5. 完整重建

npm run rebuild

该命令会执行：

1. npm run content:sync
2. npm run build

常用命令

命令	用途
npm run dev	本地开发
npm run assets:sync	按清单下载静态资源到本地目标目录
npm run content:sync	仅执行内容同步
npm run build	仅执行 Astro 构建
npm run rebuild	同步 + 构建，适合作为 AstrBot / cron 统一入口
npm run preview	本地预览构建结果

文档索引

• REQUIREMENTS.md：需求与范围
• TODO.md：当前推进计划
• docs/rebuild-trigger-spec.md：AstrBot / cron 重建触发与错误码约定
• docs/content-sync-guide.md：环境变量、映射文件、同步脚本职责、故障排查
• docs/docker-deploy.md：Docker / Compose 部署说明
• docs/linux-cron-deploy.md：宿主机定时同步 log、重建 homepage、刷新 Docker 的脚本说明
• docs/ui-design-spec.md：UI 设计规范

内容入口

日志

• 目录：src/content/logs/*.md

项目种子数据

• 文件：src/content/projects/index.json

分享种子数据

• 文件：src/content/shares/index.json

Seafile 映射

• 文件：src/content/seafile/index.json

静态资源同步清单

• 文件：src/content/static-assets/index.json
• 作用：在部署脚本里按“目录 -> 多个文件 URL”把远端图片下载到本地，例如 public/images/projects/...

推荐的内容维护边界

当前更推荐把下面这些文件视为 AstrBot 可维护输入文件：

• src/content/projects/index.json
• src/content/seafile/index.json
• src/content/shares/index.json

也就是说：

• 你在 AstrBot 里维护项目 / 分享 / 下载配置
• AstrBot 负责更新这些 JSON
• 仓库只负责在构建时读取并消费它们

这样比手工直接改 JSON 更适合日常维护，也不需要额外引入数据库或在线后台。

静态资源（例如项目封面、图库图片）如果不想直接提交到仓库，可以维护：

• src/content/static-assets/index.json

推荐格式示例：

[
  {
    "target_dir": "public/images/projects",
    "files": [
      {
        "url": "https://example.com/seafile-cover.png",
        "filename": "personal-homepage.png"
      },
      {
        "url": "https://example.com/seafile-cover-2.png",
        "filename": "devlog-pipeline.png"
      }
    ]
  },
  {
    "target_dir": "public/images/gallery",
    "files": [
      {
        "url": "https://example.com/seafile-gallery-cat.jpg",
        "filename": "cat.jpg"
      }
    ]
  }
]

然后执行：

npm run assets:sync

或直接走宿主机统一部署脚本；它会在同步 log 之前先跑一轮静态资源同步。

兼容说明：

• 现在脚本仍兼容旧格式 {"url":"...","target":"..."}；
• 但后续更推荐使用按目录分组的格式，维护起来更清楚。

统一重建入口

适合 AstrBot / cron 调用的命令：

npm run rebuild

命令结束前会输出一行结构化结果：

REBUILD_RESULT {...}

并返回明确退出码，便于通知系统判断成功 / 失败阶段。

详细约定见：

• docs/rebuild-trigger-spec.md

Docker / Compose 部署

最小启动方式：

docker compose up -d --build

默认端口：

http://localhost:8080

详细说明见：

• docs/docker-deploy.md

当前实现边界

• 当前默认策略是失败时回退 seed data，而不是保留上一轮 generated 文件
• SEAFILE_MIRROR_DOWNLOADS=true 目前只保留开关，尚未真正实现文件镜像
• npm run rebuild 当前只做同步和构建，还不包含部署阶段