Skip to content
zliuzPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

本地个人日志系统

一个单机运行的日记 / 日常记录应用: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/                                 # 删除的日志与孤儿附件

三条不变量

  1. 写入顺序是「先原子写 Markdown,再更新索引」;中途崩溃只会导致下次扫描补索引。
  2. 索引可以随时丢弃:删掉 data/index/journal.sqlite3,执行 ./journal reindex --rebuild 即可完整恢复。
  3. 在外部编辑器里改文件后,刷新浏览器就能看到(浏览、搜索、统计请求前会做增量扫描,默认 2 秒节流)。

Markdown 格式

---
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 页书。

![咖啡](2026-11-01/20261101-081200-a1b2c3d4.jpg)

## 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 与冲突处理、上传、导出。

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages