本仓库是 Hexo 静态站点工程。你日常只需要维护 source/ 下的内容，并推送到 GitHub；服务器会运行 litearch-sync.sh 自动拉取、构建并发布到线上。这是我的第一个项目。
1. 新增第一篇文章（以及第二篇、第三篇……）
文章文件放在：
source/_posts/
每篇文章都是一个 Markdown 文件，必须包含 front-matter（顶部的 --- ... ---）。
1.1 示例：创建第一篇文章
新建文件：source/_posts/我的第一篇文章.md
内容示例：
---
title: 我的第一篇文章
date: 2026-04-27 16:00:00
tags:
- 随笔
categories:
- 记录
---
这里是正文第一段。
这里是第二段。
1.2 创建第二篇文章
同理，新建：source/_posts/我的第二篇文章.md，写好标题/日期/正文即可。
提示：日期
date不写也能生成，但建议写，方便排序与归档。
2. 文章内嵌图片（推荐方式）
本项目当前配置为 post_asset_folder: false，即 不使用”每篇文章单独资源文件夹” 的模式。
因此最稳妥的做法是把图片当作站点静态资源统一管理，然后用绝对路径引用。
2.1 放置图片的位置
推荐放在：
source/img/（如果没有就新建目录）
例如：
source/img/2026/04/demo.pngsource/img/2026/04/demo.jpg
2.2 在文章里引用图片
在 Markdown 中写：
如果要控制宽度，可以用 HTML：
<img src="/img/2026/04/demo.png" style="max-width: 100%;" />
3. 本地预览（可选）
在仓库根目录运行：
npm install
npx hexo clean
npx hexo s
然后访问本地地址（Hexo 会输出）。
4. 推送到 GitHub（让服务器自动同步发布）
你本地改完内容后：
git status
git add source/ docs/ themes/
git commit -m "docs: add new posts"
git push origin main
服务器侧的 litearch-sync.sh 会定时/触发拉取 origin/main，执行：
hexo cleanhexo generate- rsync 发布到
/home/ubuntu/code/project
4.1 同步触发机制（你需要知道的关键点）
当前线上服务器采用 “push 触发 + 定时兜底” 的组合策略：
- push 触发（推荐）：GitHub Webhook 告诉服务器”有人推送了”，服务器立刻运行
litearch-sync.sh - 定时兜底：
cron每小时跑一次litearch-sync.sh，防止 webhook 漏掉或服务器短暂不可达
4.1.1 定时兜底（cron）
- 触发方式：
cron定时任务 - 推荐频率：每小时一次（
0 * * * *或@hourly） - 运行命令：
/home/ubuntu/code/litearch-sync.sh >> /home/ubuntu/secretary/logs/litearch-sync.log 2>&1
这意味着：
- 只靠 cron 的话：你
git push origin main后，服务器最迟约 1 小时内会发布 - 配合 webhook 的话：通常是 push 后立刻发布
4.1.2 push 触发（GitHub Webhook）
服务器上有一个 FastAPI Webhook 服务（端口 8888），当前工作目录在：
/home/ubuntu/code/python/secretary/scripts/webhook_listener.py
你需要把它从”触发 Obsidian 同步”改为”触发 litearch-sync.sh“，并在 GitHub 仓库里配置 webhook：
- Webhook URL：
https://litearch.cn:8888/webhook（或你实际暴露的域名/端口/路径） - Content type：
application/json - Secret：与服务端一致（避免被伪造）
- 事件：
push
注意：
litearch-sync.sh内部有flock锁，所以”cron + webhook + 手动执行”并不会并发冲突。你可以保留 cron 做兜底；日常体验主要依赖 webhook（push 即触发）。
5. 服务器手动同步（需要立刻上线时）
如果你希望”立刻上线”，可以 SSH 到服务器后运行：
bash /home/ubuntu/code/litearch-sync.sh
注意：脚本有锁（避免并发构建）。如果提示正在运行，稍等或先确认后台同步是否卡住。
5.1 如何查看是否同步成功
- 同步日志：
/home/ubuntu/secretary/logs/litearch-sync.log - 检查仓库版本：
cd /home/ubuntu/code/litearch-src
git rev-parse --short HEAD
git log -1 --oneline
6. 常见问题
6.1 修改了内容但线上没变
- 优先检查服务器是否真的完成了一次构建发布：
/home/ubuntu/secretary/logs/litearch-sync.log - 确认
git log -1是否已是你刚 push 的提交
6.2 图片 404
- 确认图片路径在
source/img/... - 文章里引用必须是以
/img/...开头的绝对路径
转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 kipleyarch@gmail.com
