224 lines
4.9 KiB
Markdown
224 lines
4.9 KiB
Markdown
# 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 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`
|
||
|
||
推荐格式示例：
|
||
|
||
```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"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
然后执行：
|
||
|
||
```bash
|
||
npm run assets:sync
|
||
```
|
||
|
||
或直接走宿主机统一部署脚本；它会在同步 log 之前先跑一轮静态资源同步。
|
||
|
||
兼容说明：
|
||
|
||
- 现在脚本仍兼容旧格式 `{"url":"...","target":"..."}`；
|
||
- 但后续更推荐使用按目录分组的格式，维护起来更清楚。
|
||
|
||
## 统一重建入口
|
||
|
||
适合 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` 当前只做同步和构建，还不包含部署阶段
|