一个单机运行的日记 / 日常记录应用:Markdown 文件保存原始内容,SQLite 只做可随时重建的索引,浏览器里可以浏览、搜索、编辑、看统计和导出备份。
- 每天一个
.md文件,正文之外可追加多条带时间戳的记录 - 标签、心情、评分、天气、图片附件
- 全文搜索(中文两字词也能搜)、日期 / 标签 / 心情筛选
- 字数、连续记录、标签与心情分布、日历热图
- Markdown 备份(带 SHA-256 清单)与离线静态 HTML 导出
- 完全本地运行,默认只监听
127.0.0.1
cd /Users/zliu/Projects/JoyNote
uv sync
./journal serve打开 http://127.0.0.1:8765。首次启动会自动创建 data/ 目录;写第一篇日志可以直接点「写今天的日志」。
./journal是一个很小的包装脚本,通过PYTHONPATH=src调用模块,避免 macOS 给.venv打上隐藏标志后 Python 3.12 跳过隐藏.pth导致的No module named 'journal'。如果uv run journal serve报同样的错,执行一次chflags -R nohidden .venv,或直接用./journal。
| 命令 | 作用 |
|---|---|
./journal serve [--port 8765] |
启动本地 Web 服务(默认拒绝非回环地址) |
./journal reindex |
增量扫描 Markdown 并更新索引 |
./journal reindex --rebuild |
删除派生数据,从 Markdown 全量重建 |
./journal check |
校验索引完整性、文件哈希与 FTS 一致性 |
./journal export --format markdown |
导出 Markdown + 附件 zip |
./journal export --format html |
导出可离线浏览的静态 HTML |
./journal gc --attachments [--apply] |
检查 / 回收未被引用的图片 |
./journal stats |
在终端打印统计摘要 |
uv run journal ... 在可编辑安装正常时也可用;./journal 更稳。
data/
├── journal/2026/11/2026-11-01.md # 事实来源
├── journal/2026/11/2026-11-01/ # 当天的图片附件
├── index/journal.sqlite3 # 派生索引,可删除重建
├── backups/ # 导出的 zip
├── cache/thumbs/ # 缩略图缓存
└── trash/ # 删除的日志与孤儿附件
三条不变量
- 写入顺序是「先原子写 Markdown,再更新索引」;中途崩溃只会导致下次扫描补索引。
- 索引可以随时丢弃:删掉
data/index/journal.sqlite3,执行./journal reindex --rebuild即可完整恢复。 - 在外部编辑器里改文件后,刷新浏览器就能看到(浏览、搜索、统计请求前会做增量扫描,默认 2 秒节流)。
---
date: "2026-11-01"
title: "公园与阅读"
tags: [life, reading]
mood: 4
rating: 4
weather: "晴"
created: "2026-11-01T08:12:00+08:00"
updated: "2026-11-01T22:41:09+08:00"
---
今天的主线是休息和阅读,下午去了公园。
## 08:12
<!-- entry-meta: tags=coffee, morning | mood=3 -->
早上在街角咖啡店读了 20 页书。

## 22:35 · 读完一章
<!-- entry-meta: tags=reading | mood=5 -->
晚上终于读完了这一章。规则:
- 一天一个文件,文件名必须为
YYYY-MM-DD.md;frontmatter 里的date与文件名不一致时以文件名优先,并在页面上给出警告。 date和时间戳请加引号,避免 YAML 自动转成日期对象。- 带时间戳的二级标题
## HH:MM或## HH:MM:SS表示一条记录;·、-、—后面的内容是条目标题。 - 代码围栏里的
## 09:00不会被误判为条目。 - 条目可选的元数据写在标题下第一行:
<!-- entry-meta: tags=a, b | mood=3 -->,大多数 Markdown 渲染器不会显示它。 - 同一天出现相同的
HH:MM时,第二条起使用08:12#2作为内部键,页面锚点为#entry-0812-2。 - 图片路径相对于当天 Markdown 文件;Web 渲染时自动改写为
/media/...,不会改动源文件。 - 未知的 frontmatter 字段会原样保留。
索引使用 SQLite FTS5 的 trigram 分词器:
- 3 个字符及以上走全文索引,按
bm25排序(标题权重最高),并生成高亮摘要; - 1–2 个字符(如「天气」「咖啡」)无法被 trigram MATCH 命中,自动改用
LIKE模糊匹配; - 长词与短词同时出现时,两种条件取交集;
- 支持日期范围、标签(全部 / 任一)、心情筛选,查询参数全部绑定,不暴露原始 FTS 语法。
trigram 是子串语义(搜 cat 也会命中 category);对个人中文日志足够。若以后需要更精确的中文分词,可以再加一套 jieba + unicode61 索引。
- Web 的「管理」页和
./journal export --format markdown都会生成journal/**+manifest.json的 zip,清单里包含每个文件的 SHA-256 和大小。 - 恢复步骤:解压覆盖
data/journal→./journal reindex --rebuild→ 用./journal check校验。 - 适配 git:把
data/journal初始化成独立 git 仓库,并在journal.toml中设置backup.git_autocommit = true,保存成功后会提交一次(永不 push,失败不影响保存)。
复制或修改根目录的 journal.toml:
[journal]
data_dir = "data"
timezone = "Asia/Shanghai"
[server]
host = "127.0.0.1"
port = 8765
[upload]
max_mb = 25
[backup]
git_autocommit = false也支持环境变量:JOURNAL_ROOT、JOURNAL_DATA_DIR、JOURNAL_TZ、JOURNAL_HOST、JOURNAL_PORT。优先级:命令行 / 环境变量 > journal.toml > 默认值。
这是单用户本地应用,没有账号系统,但仍有基本的浏览器侧防护:
- 默认只绑定
127.0.0.1,非回环地址需要显式--allow-remote; - 所有写操作强制校验 CSRF token;
Origin只拦截明确的外部 HTTP(S) 域名,放行null、WebView 自定义协议与本机/私有地址(兼容 VSCode Simple Browser、端口转发); - Flask
TRUSTED_HOSTS限制为 localhost,降低 DNS rebinding 风险; - 上传仅允许 jpg/png/gif/webp,Pillow 解码校验,禁 SVG,文件名由服务端生成;
- Markdown 渲染默认转义原始 HTML,配合 CSP、
X-Content-Type-Options、X-Frame-Options; - 正常使用不会开启 Flask debug 模式。
注意:data/ 与导出的备份默认不加密,请自行保管。
uv run pytest -q
uv run ruff check src tests测试覆盖:Markdown 解析往返、代码围栏、重复时间、坏 YAML、索引增量 / 重建、外部编辑检测、短词 / 长词搜索、统计、CSRF 与冲突处理、上传、导出。