「纸上」纸砚台 — 自托管 Markdown 博客系统 (FastAPI + Jinja2)
  • Python 28.6%
  • CSS 28.2%
  • HTML 21.1%
  • JavaScript 16.1%
  • Shell 4.6%
  • Other 1.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Paper Blog 43e4c3db77 docs: 采用 MIT License
- 新增 LICENSE(MIT,Copyright 2026 flykhan)
- README 许可章节:代码 MIT;站点文章/图片内容版权保留;第三方依赖各自许可
- Dockerfile 早已在 OCI 标签声明 licenses=MIT,无需改镜像
2026-11-19 00:09:35 +08:00
app fix: 修复后台移动端表格裁切 + 同步 1.1.1 发布信息 2026-11-19 00:03:08 +08:00
docker feat: 「纸上」自托管 Markdown 博客系统 2026-11-18 17:58:34 +08:00
scripts feat: 「纸上」自托管 Markdown 博客系统 2026-11-18 17:58:34 +08:00
.dockerignore feat: 「纸上」自托管 Markdown 博客系统 2026-11-18 17:58:34 +08:00
.env.example feat: Markdown 批量导入 + /uploads 图片服务(含 Halo 迁移) 2026-11-18 21:38:27 +08:00
.gitignore feat: 「纸上」自托管 Markdown 博客系统 2026-11-18 17:58:34 +08:00
docker-compose.release.yml fix: 修复后台移动端表格裁切 + 同步 1.1.1 发布信息 2026-11-19 00:03:08 +08:00
docker-compose.yml feat: Markdown 批量导入 + /uploads 图片服务(含 Halo 迁移) 2026-11-18 21:38:27 +08:00
Dockerfile feat: 「纸上」自托管 Markdown 博客系统 2026-11-18 17:58:34 +08:00
LICENSE docs: 采用 MIT License 2026-11-19 00:09:35 +08:00
Makefile feat: 「纸上」自托管 Markdown 博客系统 2026-11-18 17:58:34 +08:00
README.md docs: 采用 MIT License 2026-11-19 00:09:35 +08:00
requirements.txt feat: Markdown 批量导入 + /uploads 图片服务(含 Halo 迁移) 2026-11-18 21:38:27 +08:00
SPEC.md feat: Markdown 批量导入 + /uploads 图片服务(含 Halo 迁移) 2026-11-18 21:38:27 +08:00

「纸上」— 自托管 Markdown 博客系统

纸上 是一个自托管的单用户博客系统。服务端渲染、无前端构建、无 CDN 依赖,克隆下来一条 docker compose up -d --build 就能拥有一个干净、耐读、完全离线可运行的写作空间。

  • 形态:FastAPI + Jinja2 服务端渲染的多页应用,SQLite 单文件存储
  • 风格:文艺杂志 / 纸质手账感,衬线大标题、窄栏排版、赤陶色点缀
  • 交付:多阶段 Docker 构建,非 root 运行,数据卷持久化,内置健康检查

目录


功能特性

  • Markdown 写作:标准 Markdown 渲染,编辑页支持实时预览、字数统计、Ctrl/Cmd+S 保存
  • 草稿 / 发布:草稿仅后台可见,发布后进入首页、归档、标签、RSS 与 sitemap
  • 首页编辑化:站点 Hero 简介 + 精选大卡片(自动取正文首图作封面)
  • 标签与归档:标签云(按文章数分档)、按年/月归档、按标签筛选
  • 站内搜索:即时搜索(输入即出结果、关键词高亮、/ 快捷键),并保留无 JS 的服务端搜索
  • Markdown 导入:后台上传多个 .md(支持 YAML frontmatter),可批量导入、保留原始日期与草稿状态
  • RSS 与 sitemap:自动生成 /feed.xml、/sitemap.xml、/robots.txt,便于订阅与搜索引擎收录
  • 文章阅读体验:自动目录(桌面侧栏 / 移动端抽屉)、代码块语言角标与一键复制、图片灯箱、上下篇与相关推荐、作者签名
  • 关于页:作者卡(头像首字、简介、文章/标签统计)+ 独立 Markdown 正文
  • 分享与 SEO:Open Graph / Twitter Card / JSON-LD、自动分享图、RSS
  • 评论系统:匿名评论,默认需要后台审核后才公开;内置蜜罐字段防垃圾评论
  • 后台管理:登录、仪表盘、文章管理、评论审核、站点设置、修改密码
  • 站点设置:标题、副标题、描述、作者信息、页脚、关于页、每页文章数、评论开关
  • 深色模式:跟随系统或手动切换,localStorage 持久化,无闪烁
  • 响应式:360px–1440px 自适应,手机 / 平板 / 桌面均可阅读
  • 无外部依赖:不引用任何 CDN、在线字体、第三方 JS/CSS,可完全离线运行
  • 容器友好:非 root(UID 10001)、/data 数据卷、HEALTHCHECK、优雅停机

Markdown 导入

后台导航「导入」(/admin/import),可拖拽或选择多个 Markdown 文件批量导入:

  • 支持格式:.md / .markdown / .txt,单文件 ≤5MB,单次最多 50 个文件;正文 ≤200000 字符。
  • frontmatter(可选):title、date、tags、slug、summary、status / draft。 缺省时标题回退到正文首个 # H1 或文件名,slug 由标题生成,摘要自动截取正文。
  • 日期:支持 2024-04-17T11:52:50+08:00、2024-04-17 11:52:50、2024-04-17、Unix 时间戳; 无时区按 SITE_TZ 解释,页面按站点时区展示。
  • 选项:默认发布状态(frontmatter 中的 status/draft 优先)、默认标签、slug 冲突策略(跳过 / 覆盖)。
  • 结果:逐条显示新建 / 更新 / 跳过 / 失败,并附文章编辑链接。
---
title: 我的第一篇文章
date: 2024-04-17 11:52:50
tags: [随笔, 技术]
slug: my-first-post
summary: 一句话摘要
status: published
---

# 正文标题

正文内容……

从 Halo / Hexo / Hugo 等博客迁移:先从原博客导出 Markdown(保留 frontmatter),再批量导入; 图片建议上传到数据卷的 /data/uploads/,Markdown 中用 /uploads/图片名 引用即可随站点一起提供。

安全提示:文章内容按「管理员可信内容」处理,Markdown 中的内联 HTML 会被原样渲染;导入第三方来源的 HTML 前请先自行清洗。


技术栈

层 选型
Web 框架 FastAPI + Uvicorn
模板 Jinja2(StrictUndefined,服务端渲染)
存储 SQLite(Python 标准库 sqlite3)
Markdown markdown(Python)
前端 原生 HTML / CSS / JavaScript,无构建步骤
运行时 Python 3.12(Docker);本地 3.9+
部署 Docker 多阶段构建 + Docker Compose

快速开始(Docker)

前置要求

  • Docker 24+
  • Docker Compose v2.24+(使用 env_file.required: false 需要该版本;更低版本请先手动创建 .env)

一条命令启动

git clone <仓库地址> myblog
cd myblog

# 可选:准备环境变量(不创建也能直接启动,全部有默认值)
cp .env.example .env
# 按需修改 .env,重点:ADMIN_PASSWORD、SECRET_KEY、SITE_URL

docker compose up -d --build

启动后访问:

页面 地址
前台首页 http://localhost:8080
后台登录 http://localhost:8080/admin/login

容器端口默认只绑定 127.0.0.1,公网访问请按安全建议用 Nginx / Caddy 反向代理并启用 HTTPS。

首次启动管理员:默认用户名 admin;若未设置 ADMIN_PASSWORD,系统会生成随机初始密码:

  • 启动日志:docker compose logs blog | grep 初始密码
  • 或容器内文件:docker compose exec blog cat /data/initial_admin_password.txt

登录后请立即在「后台 → 设置」修改密码(后台也会显示醒目提醒)。 想固定初始密码,可在 .env 中设置 ADMIN_PASSWORD=你的强密码 后首次启动。 若未设置 SECRET_KEY,后端会自动生成并保存到 /data/.secret_key,重启后会话不会失效。

检查状态

docker compose ps          # STATUS 一列显示 healthy 即正常
docker compose logs -f     # 查看日志
curl http://localhost:8080/healthz   # {"status":"ok"}

停止服务(保留数据):

docker compose down

需要升级版本时:

git pull
docker compose up -d --build   # 数据卷 blog-data 会保留

已发布镜像(Docker Hub)

镜像:flykhan/zhishang-blog(linux/amd64),manifest digest:

sha256:c57c695ed489b06f90f11d8f9af741dc4393331b9749781342536b5ed634fc77
Tag 说明
1.1.1 固定版本(当前最新:三波设计升级 + 后台移动端适配修复)
1.1.0 上一版(保留)
1.1 1.1.x 版本线
1.0.0 更早版本(保留)
latest 最新构建
docker pull flykhan/zhishang-blog:1.1.1

# 使用仓库内 release compose(不构建,直接拉镜像)
docker compose -f docker-compose.release.yml up -d

镜像不含站点数据与密钥;首次启动会自动初始化 SQLite,并按 ADMIN_PASSWORD 环境变量创建管理员(未设置时生成随机密码写入 /data/initial_admin_password.txt)。升级前请先备份数据卷。


本地开发

本地开发不依赖 Docker,只需 Python 3.9+:

python3 -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 使用本地数据目录(默认 ./data/blog.db,首次启动自动建表并创建管理员)
export DB_PATH=./data/blog.db
export SITE_URL=http://localhost:8000
export ADMIN_USERNAME=admin
export ADMIN_PASSWORD=admin123

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

打开 http://localhost:8000。首次启动日志中会出现默认管理员密码的提示警告。

本地 SQLite 文件位于 ./data/blog.db(已被 .gitignore 忽略),删除它即可重置全站数据。


环境变量

所有变量均有安全缺省值,缺少 .env 也能直接启动。docker compose 会自动读取项目根目录的 .env 用于变量插值,并注入容器。

变量 默认值 说明
SECRET_KEY 自动生成并持久化到 /data/.secret_key 会话签名密钥。生产环境建议显式设置随机值,更换后所有登录会话失效
DB_PATH ./data/blog.db(容器内 /data/blog.db) SQLite 数据库路径;compose 中固定为 /data/blog.db
ADMIN_USERNAME admin 首次初始化管理员用户名(仅数据库为空时生效)
ADMIN_PASSWORD 随机生成 首次初始化管理员密码;留空时随机生成并写入 /data/initial_admin_password.txt、打印到启动日志
TRUST_PROXY false 反向代理后设为 true,从 X-Forwarded-For 取真实客户端 IP(限流用);直连时保持 false 防伪造
MAX_BODY_BYTES 1048576 单次请求体大小上限(字节),超限返回 413
MAX_IMPORT_BYTES 26214400 后台 Markdown 多文件导入的请求体上限(默认 25MiB)
SITE_URL http://localhost:8080 RSS / sitemap 绝对链接前缀,部署公网时改成真实域名
SITE_TZ Asia/Shanghai 展示时区(数据库始终以 UTC 存储)
BLOG_PORT 8080 宿主机映射端口(容器内固定 8000)
ALLOW_COMMENTS true 评论功能的初始化默认值(之后以后台设置为准)
COOKIE_SECURE false HTTPS 部署时设为 true,Cookie 带 Secure 标记
SESSION_MAX_AGE 604800(7 天) 会话有效期(秒)

生成 SECRET_KEY 的方法:

python -c "import secrets; print(secrets.token_hex(32))"

示例 .env:

SECRET_KEY=替换为上面命令生成的随机字符串
ADMIN_PASSWORD=替换为强密码
SITE_URL=https://blog.example.com
BLOG_PORT=8080
COOKIE_SECURE=true

修改环境变量后重新应用:

docker compose up -d

目录结构

myblog/
├── SPEC.md                  # 接口契约与实现规范(开发文档)
├── requirements.txt         # Python 依赖
├── app/                     # 应用源码
│   ├── main.py              # FastAPI 入口(app.main:app)
│   ├── config.py            # 环境变量与配置
│   ├── db.py                # SQLite 初始化与连接
│   ├── auth.py              # 登录会话 / CSRF
│   ├── repo.py              # 数据访问层
│   ├── utils.py             # 通用工具
│   ├── markdown_render.py   # Markdown 渲染
│   ├── routes_public.py     # 前台路由
│   ├── routes_admin.py      # 后台路由
│   ├── templates/           # Jinja2 模板
│   └── static/              # CSS / JS / favicon(无外部依赖)
├── docker/
│   └── entrypoint.sh        # 容器入口:修正 /data 权限后降权 exec
├── scripts/
│   └── smoke_test.sh        # 端到端冒烟测试(bash + curl)
├── Dockerfile               # 多阶段构建
├── docker-compose.yml       # 一键部署
├── .dockerignore
├── .env.example             # 环境变量示例
├── Makefile                 # 常用命令封装
├── README.md
└── data/                    # 本地运行时 SQLite(已被 git 忽略)

容器内的数据布局:

/data/
├── blog.db          # SQLite 数据库(文章、评论、设置、用户)
├── .secret_key      # 未显式设置 SECRET_KEY 时自动生成
└── initial_admin_password.txt  # 未设置 ADMIN_PASSWORD 时生成的随机初始密码

数据备份与恢复

数据全部保存在 Docker 卷 blog-data 中,核心是单文件 SQLite 数据库 /data/blog.db。

方式一:在线备份数据库(推荐,无需停机)

利用 Python 标准库 sqlite3.backup() 做一致性快照,再复制到宿主机:

# 1. 在容器内生成一致性快照
docker compose exec -T blog python -c \
  "import sqlite3; s=sqlite3.connect('/data/blog.db'); d=sqlite3.connect('/data/blog.db.bak'); s.backup(d); d.close(); s.close()"

# 2. 复制到宿主机
docker compose cp blog:/data/blog.db.bak "./blog-backup-$(date +%Y%m%d-%H%M%S).db"

# 3. 清理容器内临时快照
docker compose exec -T blog rm -f /data/blog.db.bak

方式二:备份整个数据卷(含 SECRET_KEY)

停机后打包整个卷更彻底,适合迁移服务器:

docker compose stop blog
docker run --rm -v blog-data:/data -v "$PWD":/backup alpine \
  tar czf "/backup/blog-data-$(date +%Y%m%d).tar.gz" -C /data .
docker compose start blog

未设置 SECRET_KEY 时,密钥保存在 /data/.secret_key。迁移或恢复时一并保留可避免所有用户被强制重新登录。

恢复

恢复数据库文件(服务已停止,避免覆盖正在使用的数据库):

docker compose stop blog

# 用备份覆盖容器卷中的数据库(--entrypoint 绕过降权入口,以 root 写入卷)
docker compose run --rm --no-deps --entrypoint sh blog \
  -c 'cat > /data/blog.db' < blog-backup-20261118-093000.db
docker compose run --rm --no-deps --entrypoint sh blog \
  -c 'chown 10001:10001 /data/blog.db'

docker compose start blog

恢复整个数据卷:

docker compose down
docker volume rm blog-data
docker volume create blog-data
docker run --rm -v blog-data:/data -v "$PWD":/backup alpine \
  sh -c 'tar xzf /backup/blog-data-20261118.tar.gz -C /data && chown -R 10001:10001 /data'
docker compose up -d

备份文件包含站点全部内容,请妥善保管并避免提交到版本库(.gitignore 已忽略 *.db 与 backups/)。


安全建议

  1. 立即修改初始密码:登录后进入「后台 → 设置 → 修改密码」。未设置 ADMIN_PASSWORD 时密码是随机生成的,但仍建议改成只有你知道的强密码。
  2. 显式设置 SECRET_KEY:在 .env 中使用随机值(python -c "import secrets; print(secrets.token_hex(32))"),并妥善保管 .env。
  3. 生产环境务必启用 HTTPS:通过 Nginx / Caddy 等反向代理终止 TLS,并设置 COOKIE_SECURE=true、SITE_URL=https://你的域名。
  4. 不要直接暴露后台端口到公网:仅将 8080 映射到本机(如 127.0.0.1:8080:8000),由反向代理对外提供服务;或使用防火墙 / 内网访问。
  5. 限制管理入口:如需更高安全性,可在反向代理层对 /admin 增加 IP 白名单或额外认证。
  6. 定期备份:按上文方案定期备份数据库与 .secret_key,并验证恢复流程。
  7. 及时更新:关注基础镜像与应用依赖的安全更新,升级后重新构建镜像。
  8. 评论默认审核:保持评论审核开启,避免垃圾内容直接公开。

反向代理示例

Caddy(自动申请证书):

blog.example.com {
    reverse_proxy 127.0.0.1:8080
}

Nginx(TLS 由 certbot 等管理):

server {
    listen 443 ssl;
    http2 on;
    server_name blog.example.com;

    ssl_certificate     /etc/letsencrypt/live/blog.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/blog.example.com/privkey.pem;

    client_max_body_size 2m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

此时修改 .env:

SITE_URL=https://blog.example.com
COOKIE_SECURE=true
# 反向代理后启用,限流才能拿到真实客户端 IP
TRUST_PROXY=true
# 公网部署时建议改成只绑定本机,由反向代理访问
# BLOG_PORT=8080(配合 compose 端口改为 127.0.0.1:8080:8000)

常用命令

项目提供 Makefile 封装:

make help      # 查看所有目标
make init      # 从 .env.example 生成 .env
make build     # 构建镜像
make up        # 后台启动(首次自动构建)
make down      # 停止并移除容器(保留数据卷)
make restart   # 重启服务
make logs      # 跟踪日志
make ps        # 查看状态
make shell     # 进入容器 shell
make smoke     # 执行冒烟测试
make clean     # 停止并删除容器、数据卷与镜像(危险:删除所有数据)

不习惯 make 时直接用 compose:

docker compose up -d --build
docker compose logs -f
docker compose down

冒烟测试

scripts/smoke_test.sh 使用纯 bash + curl(不需要 jq / Python),对运行中的实例执行端到端验证:

# 密码默认值仅适用于显式设置了 ADMIN_PASSWORD=admin123 的实例;
# 随机初始密码请从日志或 /data/initial_admin_password.txt 获取后传入。
BASE_URL=http://localhost:8080 ADMIN_USER=admin ADMIN_PASS=你的密码 ./scripts/smoke_test.sh
./scripts/smoke_test.sh http://localhost:8080 admin 你的密码

覆盖链路:

  1. GET /healthz 健康检查
  2. 登录(cookie jar,从登录页解析 csrf_token)
  3. 新建并发布文章(status=published)
  4. 首页与文章详情页可见
  5. /feed.xml RSS 可访问且包含新文章
  6. 后台设置页可访问
  7. 匿名提交评论(应进入待审核状态、暂不公开)
  8. 后台审核通过评论
  9. 文章页出现已审核评论
  10. 删除文章,文章页返回 404
  11. 退出登录,后台访问被重定向到登录页

每一步输出 [PASS] / [FAIL],结束时汇总;存在失败时退出码为 1,可直接接入 CI:

docker compose up -d --build
make smoke

常见问题(FAQ)

1. 端口 8080 被占用 / 想换端口

在 .env 中修改 BLOG_PORT,然后 docker compose up -d:

BLOG_PORT=9090

容器内始终监听 8000,只有宿主机映射端口变化。

2. 忘记管理员密码怎么办

系统目前不提供邮件找回。建议:

  • 若有数据库备份,按恢复流程回滚到修改密码前;
  • 若已无可用密码且数据可以接受丢失,可删除数据卷重新初始化:
    docker compose down -v
    docker compose up -d --build
    
    随后使用 .env 中的 ADMIN_USERNAME / ADMIN_PASSWORD 首次初始化(会丢失全部文章与评论,务必先备份)。

3. 修改 .env 后不生效

环境变量在容器创建时注入,修改后需要重建容器:

docker compose up -d --force-recreate

4. 启动后容器状态一直是 unhealthy

docker compose logs --tail=200 blog
docker compose exec blog python -c "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:8000/healthz').read())"

常见原因是应用启动异常(如依赖缺失、端口被占、数据库权限问题),日志会给出具体堆栈。

5. 数据库权限错误 / unable to open database file

入口脚本会以 root 修正 /data 所有权后降权到 UID 10001。如果手动拷贝过数据导致属主异常,可执行:

docker compose run --rm --no-deps --entrypoint sh blog -c 'chown -R 10001:10001 /data'
docker compose restart blog

6. 修改 SECRET_KEY 后所有人都要重新登录

这是预期行为:SECRET_KEY 用于签名会话 Cookie,更换后旧会话全部失效。

7. 评论提交成功但前台看不到

评论默认需要审核。登录后台 → 「评论」→ 待审列表 → 点击「通过」,刷新文章页即可看到。若站点设置中关闭了评论,前台将不显示评论表单。

8. 时区/日期显示不对

设置 SITE_TZ(如 Asia/Shanghai)后重建容器。数据库中的时间始终以 UTC 保存,仅展示时区不同。

9. 能离线/内网部署吗

可以。页面不引用任何外部 CDN、在线字体或第三方脚本,镜像构建完成后可完全离线运行。首次构建需要能访问 PyPI 拉取 Python 依赖。

10. 支持 ARM64 / 树莓派吗

基础镜像 python:3.12-slim 提供多架构版本,docker compose build 会在本机架构上正常构建。

11. 如何升级并保留数据

git pull
docker compose up -d --build

数据保存在命名卷 blog-data 中,重建镜像不会影响文章、评论与设置。升级前建议先备份。


许可

  • 程序代码:以 MIT License 开源。可自由使用、修改、分发、商用,保留版权与许可声明即可;Docker 镜像也已在 OCI 元数据中声明 licenses=MIT。
  • 站点内容(数据库//data 中的文章、上传图片、站点文案等):版权归作者所有,默认保留所有权利;未经作者许可请勿转载。如果你希望文章也采用开放许可,可自行改为 CC BY / CC BY-NC-SA 等。
  • 第三方依赖(FastAPI、Jinja2、python-markdown、PyYAML 等):遵循各自的开源许可证。