# personal-homepage

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

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

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

## 当前能力

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

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

复制示例文件：

```bash
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. 本地开发

```bash
npm run dev
```

### 4. 手动同步内容

```bash
npm run content:sync
```

### 5. 完整重建

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

## 推荐的内容维护边界

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

- `src/content/projects/index.json`
- `src/content/seafile/index.json`
- `src/content/shares/index.json`

也就是说：

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

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

## 统一重建入口

适合 AstrBot / cron 调用的命令：

```bash
npm run rebuild
```

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

```text
REBUILD_RESULT {...}
```

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

详细约定见：

- `docs/rebuild-trigger-spec.md`

## Docker / Compose 部署

最小启动方式：

```bash
docker compose up -d --build
```

默认端口：

```text
http://localhost:8080
```

详细说明见：

- `docs/docker-deploy.md`

## 当前实现边界

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