4.9 KiB

Raw Permalink Blame History

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

该命令会执行：

npm run content:sync
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 当前只做同步和构建，还不包含部署阶段

4.9 KiB Raw Permalink Blame History Unescape Escape