# 从零搭建一个 Node.js 文档管理系统：功能迭代记录与技术复盘

> 本文为一个「单位文档管理系统」从 0 到功能完备的开发过程记录，涵盖架构选型、核心功能实现、遇到的问题及解决方案。适合想快速上手全栈开发或了解本地化轻量系统搭建的开发者。

---

## 一、项目背景与目标

在一个单位内部，文档管理往往是一个被低估的需求：员工需要将文件分类归档、跨用户共享重要资料、管理员需要审核注册用户并管控权限。市面上不少方案过于臃肿（SaaS 订阅），或者需要部署复杂的数据库服务（MySQL / PostgreSQL）。

于是决定用 **Node.js + Express + SQLite + 原生 HTML/JS** 搭建一个轻量级、自包含的文档管理系统，部署在单位内网服务器上即可使用。

**核心需求：**
- 用户注册 / 登录 / 密码修改
- 个人文档上传、下载、预览、删除
- 文件夹管理，支持文档归档
- 共享文档：用户可将文档/文件夹设为共享，他人可见
- 管理员审核注册用户、禁用账号、重置密码
- 在线扫描上传（手机拍照合成 PDF）
- 系统标题和图标可自定义

---

## 二、技术选型

| 层级 | 选型 | 理由 |
|------|------|------|
| 运行时 | Node.js 22.22.2 | LTS 稳定版，生态完善 |
| Web 框架 | Express 4.19 | 轻量，中间件生态成熟 |
| 数据库 | better-sqlite3 | 同步 API，无需额外服务，单文件存储 |
| 文件存储 | 本地磁盘（public/uploads） | 简单直接，配合 Express 静态服务 |
| 鉴权 | cookie-session + bcryptjs | 会话保存在 Cookie，密码哈希存储 |
| 文件上传 | multer | 表单文件解析，支持大小限制和类型过滤 |
| PDF 合成 | pdf-lib | 将扫描图片合成为 PDF |

**为什么不用 MySQL？** 系统规模小，SQLite 完全够用，且无需维护独立数据库服务，`doc-mgr.db` 一个文件即可备份迁移。

---

## 三、项目结构

```
doc-mgr/
├── server.js          # Express 主入口，路由集中定义
├── db.js              # SQLite 初始化与建表逻辑
├── package.json
├── public/
│   ├── index.html     # 主页面（个人文档 + 共享文档 + 管理后台）
│   ├── login.html     # 登录/注册页
│   ├── scan.html      # 在线扫描页
│   ├── favicon.svg    # 默认图标
│   ├── css/app.css    # 样式
│   ├── js/common.js   # API 封装、工具函数
│   ├── js/app.js      # 主交互逻辑
│   └── uploads/       # 文件存储目录
```

---

## 四、数据库设计

`db.js` 负责建表和增量兼容（`addColumnIfNotExists` 确保存量库可平滑升级）：

```sql
-- 用户表
CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  username TEXT UNIQUE NOT NULL,
  password TEXT NOT NULL,      -- bcrypt 哈希
  realname TEXT NOT NULL,      -- 真实姓名（注册必填）
  role TEXT NOT NULL DEFAULT 'user',  -- user | admin
  status TEXT NOT NULL DEFAULT 'approved',  -- pending | approved | rejected | disabled
  created_at TEXT
);

-- 文档表
CREATE TABLE docs (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  owner_id INTEGER NOT NULL,
  scope TEXT NOT NULL DEFAULT 'private',  -- private | shared
  title TEXT NOT NULL,
  description TEXT,
  category TEXT,
  file_path TEXT NOT NULL,     -- 相对路径，指向 public/uploads
  file_type TEXT,              -- pdf | jpg | png ...
  file_size INTEGER,
  folder_id INTEGER,           -- 所属文件夹（NULL = 根目录）
  hidden INTEGER DEFAULT 0,    -- 管理员隐藏标记（仅共享文档有效）
  created_at TEXT,
  FOREIGN KEY (owner_id) REFERENCES users(id)
);

-- 文件夹表
CREATE TABLE folders (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  owner_id INTEGER NOT NULL,
  name TEXT NOT NULL,
  scope TEXT NOT NULL DEFAULT 'private',  -- private | shared
  hidden INTEGER DEFAULT 0,
  created_at TEXT,
  FOREIGN KEY (owner_id) REFERENCES users(id)
);

-- 操作日志表
CREATE TABLE doc_logs (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  doc_id INTEGER NOT NULL,
  user_id INTEGER NOT NULL,
  action TEXT NOT NULL,  -- create | view | download | delete | share | hide
  created_at TEXT,
  FOREIGN KEY (doc_id) REFERENCES docs(id),
  FOREIGN KEY (user_id) REFERENCES users(id)
);

-- 系统设置表（键值对）
CREATE TABLE settings (
  key TEXT PRIMARY KEY,
  value TEXT
);
```

**设计亮点：**
- 所有文档归个人，`scope='shared'` 表示「已设为共享」，便于权限控制统一
- `folder_id` 为 nullable，支持文档在「根目录」和「文件夹内」两种状态
- `hidden` 字段区分于 `scope`，实现管理员对共享内容的「隐藏」而不「删除」

---

## 五、核心功能实现

### 5.1 鉴权与登录

使用 `cookie-session` 中间件，会话保存在浏览器 Cookie 中：

```javascript
app.use(session({
  name: 'docmgr_session',
  keys: ['doc-mgr-secret-key-2024'],
  maxAge: 24 * 60 * 60 * 1000,
  httpOnly: true,
  sameSite: 'strict',
}));
```

密码使用 bcryptjs 哈希存储，注册时强制要求真实姓名：

```javascript
const hash = bcrypt.hashSync(password, 10);
db.prepare('INSERT INTO users (...) VALUES (...)').run(username, hash, realname, 'user', 'pending');
```

登录流程同时检查账号状态：

```javascript
if (u.status === 'pending') return res.jsonError('账号待管理员审核');
if (u.status === 'disabled') return res.jsonError('账号已被禁用');
```

### 5.2 文档上传与下载

上传使用 multer，支持 PDF/JPG/PNG/GIF/BMP/TXT/DOCX/XLSX，单文件最大 50MB：

```javascript
const upload = multer({
  storage: multer.diskStorage({...}),
  limits: { fileSize: 50 * 1024 * 1024 },
  fileFilter: (req, file, cb) => {
    const allow = ['.pdf','.jpg','.jpeg','.png','.gif','.bmp','.txt','.docx','.xlsx'];
    const ext = path.extname(file.originalname).toLowerCase();
    if (allow.includes(ext)) cb(null, true);
    else cb(new Error('不支持的文件类型: ' + ext));
  },
});
```

**下载接口的设计：** 为了让下载后的文件能被正确打开，文件名使用文档标题（中文）而非服务器内部文件名：

```javascript
app.get('/api/docs/:id/download', requireLogin, (req, res) => {
  const doc = db.prepare('SELECT * FROM docs WHERE id=?').get(req.params.id);
  if (!doc) return res.jsonError('文档不存在', 404);
  // 权限校验：本人 / 管理员 / 共享文档 / 文件夹内共享文档
  const folder = doc.folder_id
    ? db.prepare('SELECT scope FROM folders WHERE id=?').get(doc.folder_id)
    : null;
  const folderShared = folder && folder.scope === 'shared';
  const visible = doc.owner_id === req.session.user.id
    || isAdmin
    || doc.scope === 'shared'
    || folderShared;
  if (!visible) return res.jsonError('无权访问该文档', 403);
  // 用文档标题作为文件名
  const ext = doc.file_type ? '.' + doc.file_type : '';
  const safe = (doc.title || 'document').replace(/[\\/:*?"<>|\r\n]/g, '_').slice(0, 80);
  const fname = safe + ext;
  res.download(doc.file_path, fname);
});
```

### 5.3 文件夹下钻与共享文档三级导航

共享文档采用**三级导航结构**：

```
共享文档（根目录：用户列表）
  └── 张三（用户空间：文件夹卡片 + 散文件）
        └── 部门（文件夹内：文件列表）
```

**关键逻辑（后端）：** 查询共享文档时，同时返回共享文件夹和单独共享的文档，前端按上传者分组展示：

```javascript
// 共享文件夹
const folderRows = db.prepare(`
  SELECT f.*, u.realname AS owner_realname
  FROM folders f JOIN users u ON u.id=f.owner_id
  WHERE f.scope='shared' AND (f.hidden=0 OR ? OR f.owner_id=?)
`).all(isAdmin ? 1 : 0, uid);

// 共享文件（单独共享 或 在可见的共享文件夹内）
const docRows = db.prepare(`
  SELECT d.*, u.realname AS owner_realname,
         f.id AS f_id, f.name AS f_name
  FROM docs d
  JOIN users u ON u.id=d.owner_id
  LEFT JOIN folders f ON f.id=d.folder_id
  WHERE (
    (d.scope='shared' AND d.hidden=0)
    OR (f.id IS NOT NULL AND f.scope='shared' AND f.hidden=0)
  )
`).all();
```

前端 JS 根据 `kind` 字段区分文件夹（`'folder'`）和文件（`'file'`），渲染不同的卡片交互。

### 5.4 在线扫描（多张图片合成 PDF）

扫描页面 `scan.html` 调用设备摄像头，拍摄多张照片后通过 `pdf-lib` 合成：

```javascript
app.post('/api/docs/scan', requireLogin, async (req, res) => {
  const { images, title, folder_id } = req.body;
  const pdfDoc = await PDFDocument.create();
  for (const dataUrl of images) {
    const base64 = dataUrl.replace(/^data:image\/\w+;base64,/, '');
    const buf = Buffer.from(base64, 'base64');
    let img;
    if (/^data:image\/jpeg/.test(dataUrl)) img = await pdfDoc.embedJpg(buf);
    else if (/^data:image\/png/.test(dataUrl)) img = await pdfDoc.embedPng(buf);
    const page = pdfDoc.addPage([img.width, img.height]);
    page.drawImage(img, { x: 0, y: 0, width: img.width, height: img.height });
  }
  const pdfBytes = await pdfDoc.save();
  // 存入磁盘并记录到数据库
  fs.writeFileSync(fullPath, pdfBytes);
  db.prepare('INSERT INTO docs ...').run(...);
});
```

### 5.5 用户管理（禁用/重置密码）

**移除删除用户功能，改为禁用：**

```javascript
app.post('/api/admin/users/:id/disable', requireAdmin, (req, res) => {
  const disabled = req.body.disabled === true || req.body.disabled === 'true';
  db.prepare('UPDATE users SET status=? WHERE id=?')
    .run(disabled ? 'disabled' : 'approved', req.params.id);
});
```

**管理员重置用户密码：**

```javascript
app.post('/api/admin/users/:id/password', requireAdmin, (req, res) => {
  const pwd = (req.body.password || '').toString();
  if (pwd.length < 6) return res.jsonError('新密码至少 6 位');
  const hash = bcrypt.hashSync(pwd, 10);
  db.prepare('UPDATE users SET password=? WHERE id=?').run(hash, u.id);
});
```

**用户修改自己的密码（需验证旧密码）：**

```javascript
app.post('/api/auth/password', requireLogin, (req, res) => {
  const { old_password, new_password } = req.body;
  const u = db.prepare('SELECT * FROM users WHERE id=?').get(req.session.user.id);
  if (!bcrypt.compareSync(old_password, u.password))
    return res.jsonError('旧密码不正确');
  if (old_password === new_password)
    return res.jsonError('新密码不能与旧密码相同');
  const hash = bcrypt.hashSync(new_password, 10);
  db.prepare('UPDATE users SET password=? WHERE id=?').run(hash, u.id);
});
```

### 5.6 系统设置（标题 + 图标）

系统设置存储在 `settings` 表中，通过 API 动态加载，所有页面自动应用：

```javascript
app.get('/api/settings', (req, res) => {
  const get = (k) => { const r = db.prepare('SELECT value FROM settings WHERE key=?').get(k); return r?.value || null; };
  res.jsonOk({ title: get('site_title'), icon: get('site_icon') || '/favicon.svg' });
});
```

前端 `common.js` 在每次页面加载时调用 `applySystemSettings()`，自动设置 `<title>` 和 `<link rel="icon">`：

```javascript
async function applySystemSettings() {
  const data = await fetch('/api/settings').then(r => r.json());
  const s = data.data || {};
  if (s.title) document.title = '文档管理 - ' + s.title;
  let link = document.querySelector('link[rel="icon"]');
  if (!link) { link = document.createElement('link'); link.rel = 'icon'; document.head.appendChild(link); }
  link.href = s.icon;
}
applySystemSettings();
```

---

## 六、开发过程中的关键问题与解决

### 问题 1：上传到文件夹的文件，没有在文件夹里显示

**现象：** 用户在上传时选择了文件夹，但文件仍然显示在根目录，不在文件夹中。

**排查：** 后端数据库查询确认 `folder_id` 字段已正确写入，数据无误。

**根因：** 是前端观感问题——文件夹卡片不可点击，文件散落在下方，用户误以为"文件没进去"。

**解决：** 添加文件夹点击下钻功能。用户点击文件夹卡片后，页面切换为只显示该文件夹内的文件，顶部显示面包屑导航（`文档管理 > 部门`），点击面包屑返回上级。

### 问题 2：共享文档中，非预览类文件的下载体验差

**现象：** 图片、Word、Excel 等文件无法在线预览，点击下载后文件名是服务器内部生成的乱码（如 `doc_1787369416046_678987.docx`）。

**解决：** 新增 `/api/docs/:id/download` 接口，用文档的 `title` + 扩展名作为下载文件名，并正确设置 `Content-Disposition` 头：

```javascript
res.setHeader('Content-Disposition', `attachment; filename="${safe + ext}"; filename*=UTF-8''${encodeURIComponent(safe + ext)}`);
```

同时，前端对不支持预览的文件类型，主按钮改为「📥 下载并打开」。

### 问题 3：共享页文档"散落"在外部

**现象：** 用户将单个文件设为共享（未放入文件夹），该文件在共享页中散落在其他文件之间，观感混乱。

**解决：** 引入「移动文件到文件夹」功能，允许管理员或文件主人将散文件移入对应文件夹；同时完善共享页的三级导航结构，让共享页面的信息层次更清晰。

---

## 七、权限模型总结

```
普通用户（user）：
  ✅ 登录/注册
  ✅ 上传/下载/删除自己的文档
  ✅ 创建/管理自己的文件夹
  ✅ 将自己的文档/文件夹设为共享
  ✅ 查看共享文档
  ✅ 修改自己的密码
  ❌ 无法查看他人私有文档
  ❌ 无法管理用户

管理员（admin）：
  ✅ 所有普通用户权限
  ✅ 审核注册用户（approve / reject）
  ✅ 禁用/启用用户
  ✅ 重置用户密码
  ✅ 隐藏/显示共享文档和文件夹
  ❌ 不能将其他用户降级为普通用户（防止越权）
  ❌ 不能将自己降级为普通用户（管理员身份永久固定）
```

---

## 八、运行与部署

**本地运行：**

```bash
cd doc-mgr
npm install
npm start
# 访问 http://localhost:3200
# 默认管理员: admin / admin123
```

**内网部署建议：**
- 使用 nginx 反向代理，配置 HTTPS
- 定期备份 `doc-mgr.db` 和 `public/uploads/` 目录
- 如需多人同时使用，建议将端口改为非 3200，或在 nginx 中限制 IP 白名单

---

## 九、截图示例

![01-login.png](https://developer.qcloudimg.com/http-save/yehe-12702702/19d597a4f1ae2db30d5107f950759361.png)
![03-personal-docs.png](https://developer.qcloudimg.com/http-save/yehe-12702702/0cf3812da46a21829bd5e61cdaa0fdce.png)
![04-shared-docs.png](https://developer.qcloudimg.com/http-save/yehe-12702702/31acc371808cf41f2c3b6880332ba9b2.png)

![05-user-management.png](https://developer.qcloudimg.com/http-save/yehe-12702702/e8b2d19dbed21dee7cf7f86dbf40cb15.png)
![06-settings.png](https://developer.qcloudimg.com/http-save/yehe-12702702/6a74c86d0a75aebee37cdb16e3842476.png)
![08-upload-dialog.png](https://developer.qcloudimg.com/http-save/yehe-12702702/d8f0f3d92d6dedd32e4ec6001636e66c.png)

![09-scan-page.png](https://developer.qcloudimg.com/http-save/yehe-12702702/3513acb9259e7fcc88d2f6eb3c7dbd09.png)

---

## 十、总结

本项目从一个简单的文件上传工具起步，经过多轮迭代，逐步完善了用户管理、权限控制、共享协作、系统设置等功能。过程中遇到的每个问题（文件夹下钻、下载文件名乱码、共享文档散乱）都反映了**用户体验**层面的思考——功能实现了只是第一步，让功能在正确的位置以正确的方式呈现同样重要。

**项目亮点：**
- 零外部依赖服务（SQLite + Node.js 即可运行）
- 纯前端框架（原生 HTML/CSS/JS，无构建步骤）
- 模块化的权限模型（角色严格固定，不可升降）
- 可扩展的系统设置（标题/图标可通过后台自定义）
- 完整的安全措施（bcrypt 密码哈希、cookie-session 安全配置、文件类型白名单）

---

*本文基于实际项目代码撰写，所有代码示例可直接参考 `C:\Users\admin\WorkBuddy\wdgl\doc-mgr\` 目录下的源码。*


本文为一个「单位文档管理系统」从 0 到功能完备的开发过程记录，涵盖架构选型、核心功能实现、遇到的问题及解决方案。适合想快速上手全栈开发或了解本地化轻量系统搭建的开发者。

从零搭建一个 Node.js 文档管理系统：功能迭代记录与技术复盘

编程语言

后端

开发工具

从零搭建Node.js文档管理系统，基于Express+SQLite实现轻量级全栈开发。涵盖用户注册审核、权限分级、文档上传下载、文件夹管理、共享协作、在线扫描合成PDF等核心功能。分享权限模型设计、三级导航架构、常见问题解决方案，适合快速上手内网部署的开发者参考。

文件存储

代码解释

PostgreSQL

中间件

服务器

数据库

WorkBuddy 

路由

SQLite

MySQL

SaaS

2026上云采购 | AI焕新·智启新局

tencentdb-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

从零搭建一个 Node.js 文档管理系统：功能迭代记录与技术复盘-腾讯云开发者社区-腾讯云

从零搭建一个 Node.js 文档管理系统：功能迭代记录与技术复盘

从零搭建一个 Node.js 文档管理系统：功能迭代记录与技术复盘

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐