148 lines
2.8 KiB
Markdown
148 lines
2.8 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
|
||
```
|
||
|
||
然后填写：
|
||
|
||
- `GITEA_BASE_URL`
|
||
- `GITEA_TOKEN`
|
||
- `GITEA_USERNAME`
|
||
- `SEAFILE_BASE_URL`
|
||
- `SEAFILE_TOKEN`
|
||
|
||
如果某些远端还没接好，也可以先保留为空；系统会按当前策略回退到 seed data。
|
||
|
||
### 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/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 调用的命令：
|
||
|
||
```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` 当前只做同步和构建，还不包含部署阶段
|