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

然后填写：

• GITEA_BASE_URL
• GITEA_TOKEN
• GITEA_USERNAME
• SEAFILE_BASE_URL
• SEAFILE_TOKEN

如果某些远端还没接好，也可以先保留为空；系统会按当前策略回退到 seed data。

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 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/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

统一重建入口

适合 AstrBot / cron 调用的命令：

npm run rebuild

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

REBUILD_RESULT {...}

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

详细约定见：

• docs/rebuild-trigger-spec.md

当前实现边界

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