ARTICLE · 1315908

推荐一个文档管理系统开源项目

一、项目简介

推荐一个自托管的本地文档管理系统——把 HTML / PDF / Word 上传进来，生成可分享的文档短链接，并统一管理阅读、在线编辑与访问权限。

它解决"团队里散落的 HTML 报表、PDF、Word 文档没有统一入口、没法受控分享"的问题：集中入库 → 生成短链接 → 按权限分享 → 阅读可统计 → 内容还能在线改。

二、核心功能

模块	能力
文档首页	LOGO+导航、居中搜索、按分类的公开文档统计、最近更新 6 份文档
资源列表	名称/文件名搜索、分类、排序、分页；整行可点击阅读，日期统一 `YYYY-MM-DD`
上传工作区	单/多文件上传，或导入含图片、CSS、JS 的整个目录；居中宽屏弹窗核对信息+设权限+确认入库；单文件上限 20 MiB
HTML 编辑与替换	后台直接改 HTML 源码，或进入原页面做可视化"页面内编辑"（自动保存、保留版本）；支持上传 HTML/HTM 替换当前内容，原链接、权限、浏览量全部保留
PDF / Word 阅读	PDF 直开阅读器；Word 经 LibreOffice 转 PDF 阅读（这两类不支持在线编辑）
访问控制	三种可见性：首页可见 / 仅链接可见 / 私有；公开文档可另设 6–128 位阅读密码（服务端存加盐哈希，浏览器存随机 HttpOnly 授权 Cookie，可记住 400 天或 2 小时）
后台管理	目录监听（文件变化自动入库）、回收站与恢复、站点与 SEO 设置、自定义后台地址、前台自定义导航、统计代码嵌入、HTML 向同类服务同步
数据分析	今日/累计 PV、近 7/30/90 天趋势、每日明细、累计与今日 Top 10（各带独立完整明细页，每页 20 条）、类型分布；不采集访客身份与 IP（无 UV）

REST API 齐全（/admin/api/*：登录、文档、上传 prepare/confirm、访问设置与撤销、编辑与版本、设置与监听目录、分析、公开列表、阅读路由 /:slug）。

三、项目功能亮点

HTML 是"一等公民"：不是简单存附件，而是能源码编辑 + 原文可视化编辑 + 文件替换 + 版本回溯，且替换时保留短链接/权限/浏览量/目录附件——这在同类轻量文档系统里少见。
权限模型细颗粒且贯穿全链路：HTML、PDF、Word、原始文件、共享附件都走同一套权限校验；附件权限冲突会要求统一权限或独立目录重导。
替换链路做了并发与一致性设计：先经鉴权元信息接口确认版本再提交，避免覆盖他人改动；数据库记录与附件索引同事务提交，失败按保存点回滚。
目录监听 + 可回写：外部工具生成的 HTML 放进监听目录自动入库，写回开关可控（只读目录仅更新站内）。
部署极轻：单容器 + 单个 SQLite 文件 + 两个挂载目录，镜像已内置 LibreOffice 与中文字体，开箱即用。
兼容与迁移友好：环境变量沿用 TOKDOC_* 并兼容旧 TOKHTML_*、旧库文件名、旧 Cookie 与旧阅读地址 :slug.html。
工程规范清楚：自带维护说明、部署指南、UI 规范（DESIGN.md）；GitHub Actions 在 push/PR 时跑 Node 22 测试、校验 compose、构建镜像，CI 只读权限、官方 Actions 锁 SHA。

四、项目结构

liekan-docs/
├── data/# 持久化数据（默认挂载目录）
│   ├── tokdoc.db             #   SQLite 主库（兼容旧 tokhtml.db）
│   ├── brand/#   上传的 LOGO 图片
│   ├── uploads/#   原文件与目录附件
│   ├── pages/#   生成的 HTML / PDF / Word 阅读版本
│   ├── versions/#   HTML 版本快照
│   └── trash/#   回收站
├── html-inbox/# 默认目录监听入口（容器内 /watch/html-inbox）
├── docs/
│   ├── deploy-docker.md      # 部署指南：参数、反向代理、备份、升级与回滚
│   └── maintaining.md        # 维护说明：代码结构、测试、提交范围、兼容约束
├── public/# 前后台 HTML / JavaScript / 系统样式（无前端编译步骤）
├── src/
│   ├── server.js             # 入口，启动 Fastify
│   ├── routes.js             # 前后台路由与公开 API
│   ├── config.js             # 环境变量与默认配置
│   ├── db.js                 # SQLite 建库与访问
│   ├── page-store.js         # 文档存储、上传/替换、版本与回收站
│   ├── document-access.js    # 访问方式、阅读密码与授权 Cookie
│   ├── html.js               # HTML 处理与注入
│   ├── edit-bridge.js        # 页面内编辑桥（编辑标记与自动保存）
│   ├── watch-service.js      # 目录监听与同步入库
│   ├── analytics.js          # PV 统计与排行分析
│   ├── brand.js              # LOGO/品牌资源
│   └── admin-path.js         # 自定义后台路径
├── test/# node:test 单元测试 + 前端 DOM 交互测试
├── .env.example              # 配置样例（端口/绑定地址/挂载目录/初始账号等）
├── Dockerfile                # Node 22 + LibreOffice + 中文字体
├── docker-compose.yml        # 本地持久化部署编排
├── DESIGN.md                 # UI 规范（布局、控件、日期、移动端、交互）
├── README.md / LICENSE(MIT) / package.json / package-lock.json
└── .dockerignore / .gitignore

五、技术栈

层	选型
运行时	Node.js ≥ 22.13，`"type": "module"`，原生 ESM
Web 框架	Fastify 5 （^5.12.7）
插件	`@fastify/multipart` ^9.3.0（文件上传）、`@fastify/static` ^10.1.6（静态资源）
文件监听	`chokidar` ^4.0.3
DOM 解析	`linkedom` ^0.18.12（服务端轻量解析 HTML，用于注入/编辑）
数据库	SQLite （单文件 `data/tokdoc.db`，无 ORM、无外部 DB 服务）
前端	原生 JavaScript + HTML + CSS ，无框架、无打包/编译步骤；系统 UI 样式不注入用户文档正文
文档转换	LibreOffice （`soffice` 命令行）做 Word → PDF；镜像基于 `node:22-bookworm-slim` 并预装 LibreOffice Writer 与中文字体
测试	Node 内置 `node --test`（`test/*.test.js`）
部署/CI	Dockerfile + Docker Compose v2；GitHub Actions（Node 22 测试、compose config 校验、docker build）
语言构成	JavaScript 83.6% / CSS 8.3% / HTML 8% / Dockerfile 0.1%

依赖仅 5 个，非常克制；private: true 只为防误发 npm，仓库本身公开。

六、本地快速部署启动

方式 A：Docker（推荐，开箱支持 Word 转 PDF）

前置：Docker Engine + Docker Compose v2。

git clone https://github.com/yaojingang/liekan-docs.git
cd liekan-docs
cp .env.example .env
# 必做：编辑 .env，改掉 TOKDOC_INITIAL_PASSWORD（默认是 tokdoc）
docker compose up -d --build

启动后入口：

入口	默认地址
文档首页	http://127.0.0.1:18082/
全部资源	http://127.0.0.1:18082/?view=resources
后台上传工作区	http://127.0.0.1:18082/admin
健康检查	http://127.0.0.1:18082/healthz

关键 .env 参数：TOKDOC_HOST_PORT=18082、TOKDOC_BIND_ADDR=127.0.0.1（反代场景保持本机地址；仅内网直连才用 0.0.0.0）、TOKDOC_DATA_VOLUME=./data、TOKDOC_WATCH_VOLUME=./html-inbox、TOKDOC_ALLOW_SOURCE_WRITE=false（是否允许写回监听目录源文件）、TOKDOC_ADMIN_PATH（自定义后台路径）、TOKDOC_TRUST_PROXY（受信代理 IP/CIDR，逗号分隔）。默认只绑本机，域名访问请配 Nginx/宝塔反向代理 + HTTPS。

方式 B：本地 Node.js

前置：Node 22.13+；要转换 Word 还需本机安装 LibreOffice，让 soffice 在 PATH 中（或用 TOKDOC_SOFFICE_BIN 指定路径）。

npm ci
TOKDOC_INITIAL_USERNAME=admin TOKDOC_INITIAL_PASSWORD='一个足够长的密码' npm run dev

首页 http://127.0.0.1:8080/ ，后台 http://127.0.0.1:8080/admin
注意：npm run dev 走进程环境变量，不会自动读 .env；不设初始账号时空库默认 admin / tokdoc（已有库不会被初始账号变量重置密码）。
生产启动用 npm start（node src/server.js），开发用 npm run dev（node --watch）。