

## 一、项目数据一览

先看一组数字，感受一下这个项目从零到上线的全貌：

| 指标 | 数值 |
|------|------|
| 开发周期 | 约6周（断续开发） |
| 前端Vue组件 | 18个 |
| 后端路由/服务文件 | ~30个 |
| Docker镜像大小 | ~1.2GB（含LibreOffice+字体+unrar） |
| 数据库表 | 6张 |
| API接口数 | ~25个 |
| 角色层级 | 4级 |
| 版本迭代 | v28 → v47i（约20个版本） |
| 修复的Bug数量 | ~15个（含3个重大级） |
| 部署方式 | NAS单容器 + frp内网穿透 |

## 二、全部踩坑记录汇总

这是最有价值的部分——每个坑都是真金白银换来的经验。

### 🔴 重大级Bug（导致服务不可用）

| # | 问题 | 现象 | 根因 | 解决方案 |
|---|------|------|------|---------|
| 1 | **helmet白屏** | 部署后页面完全空白，无报错 | COOP/COEP头阻止跨域JS加载 | 彻底移除helmet |
| 2 | **v34/v35代码从未部署** | 修了bug但线上没生效 | SFTP路径错误（chroot vs 真实路径） | 统一路径规范 |
| 3 | **sudo链式命令清空前端** | `rm && mkdir && tar`只有rm在sudo下 | sudo不继承&&后续命令 | 包进`sudo bash -c '...'` |
| 4 | **Dockerfile apt冲突** | 构建失败→容器被删→404 | unrar.list和debian.sources重复 | 删冗余list文件 |

### 🟡 中等级Bug（功能异常）

| # | 问题 | 根因 | 解决方案 |
|---|------|------|---------|
| 5 | **auth中间件req.user为undefined** | 解构导入`{ authMiddleware }` vs 整体导入`const auth = ...` | 统一导出/导入风格 |
| 6 | **response.data.data取不到数据** | 后端返回`{code,data,message}`但前端用`response.data` | 铁律：永远用`response.data.data` |
| 7 | **multer后req.body为空** | RBAC在multer之前执行 | multer必须在所有其他中间件之前 |
| 8 | **中文文件名乱码** | busboy默认latin1解码中文 | `Buffer.from(name,'latin1').toString('utf8')` |
| 9 | **大文件408超时** | requestTimeout=5min < 实际上传时间 | 改为10min，对齐前端 |
| 10 | **RAR预览三层叠加失效** | 中文路径不支持 + 列表解析0条 + 内文名乱码 | tmp复制+5列切片+LC_ALL=UTF-8 |

### 🟢 轻微级问题（体验优化）

| # | 问题 | 解决方案 |
|---|------|---------|
| 11 | 上传弹窗误触关闭（点击遮罩） | 删除`@click.self="$emit('close')"`，加确认逻辑 |
| 12 | 导航栏点击无响应（教学资料tab） | `handleCategoryChange`中cat==='teaching'特殊处理 |
| 13 | 统计面板status过滤无效 | 前端路由监听器修复 + Cache-Control头 |
| 14 | 活动照片上传HTTP 500 | `batchInitialStatus`变量未定义 |
| 15 | 审核操作缺少反馈提示 | 加alert/toast通知 |

## 三、Top 5 最有价值的经验

### 经验1：部署脚本比代码更重要

写代码的时间可能只占30%，剩下的70%都在跟部署较劲。SFTP路径差异、Docker构建、容器内文件更新、端口转发……每一个环节都能卡住你半天。

**我的做法**：
- 把每次成功部署的完整步骤写成文档（不是靠记忆）
- 关键路径（SFTP vs SSH）的差异写在注释里最显眼的位置
- 部署脚本加`-WhatIf`预览模式

### 经验2：「铁律文档」能救命

项目中我维护了一份编码规范"铁律"，只有6条，但每条都对应一个真实踩过的坑：

```
铁律（不可违反）：
1. auth.js 必须导出函数本身 module.exports = authMiddleware
2. 路由必须用 const auth = require('../middleware/auth') （禁止解构）
3. 前端必须用 response.data.data 访问接口数据
4. helmet 已彻底移除，禁止重新引入
5. multer 中间件顺序：upload.single → rbac → handler
6. SFTP路径用 /lucky/ ，SSH/python用 /volume1/lucky/
```

新加入的开发者（或两周后的自己）只需要读这6条就能避开90%的已知陷阱。

### 经验3：NAS部署的特殊性要提前调研

NAS不是普通Linux服务器——它有自己的限制：

| NAS特性 | 影响 | 应对 |
|--------|------|------|
| SFTP chroot | 路径和真实路径不同 | 维护两套路径映射表 |
| 资源有限(2核2G) | 不能跑重进程 | 选轻量技术栈(Node vs Java) |
| 无公网IP | 外网访问需穿透 | frp或Cloudflare Tunnel |
| Docker卷权限 | 需sudo才能访问 | 部署脚本统一sudo |
| 系统包源可能有冲突 | apt安装可能失败 | 手动检查sources.list |

如果你也要在NAS上部署应用，**先把这些限制搞清楚再开始写代码**，会省很多返工。

### 经验4：版本号策略要有意义

我采用的版本命名是递增式：v28, v29, v30...v47i。每个版本对应一次可独立部署的功能变更。这样做的好处：

- 出问题时可以精确回滚到上一个正常版本
- 和前端Vite版本戳联动（vite.config.ts里的版本号同步更新）
- 部署日志里可以清晰看到"从v46升级到v47"

### 经验5：用户反馈是最优先的产品需求来源

这个项目的几乎所有功能迭代都来自老师们的实际反馈：

| 反馈 | 衍生出的功能 |
|------|------------|
| "找不到之前传过的东西" | 「我的上传」页面 |
| "压缩包太大了不想下载就能看里面" | ZIP/RAR在线浏览 |
| "点外面就关掉了上传窗口" | UploadDialog防误触改造 |
| "RAR打不开" | 三层修复（中文路径+0条+乱码）|
| "上传大文件报错" | 超时从5min改10min |

**不要闭门造车。让真实用户尽快用起来，他们的吐槽就是你的产品路线图。** **整个七篇系列，从代码审查、文档生成到截图脱敏，WorkBuddy 都是我最得力的搭档。它把一个全栈项目的经验分享，从「工程巨债」变成了「轻松可写」——说它把我的内容产出效率提升了好几倍，一点不夸张。**

## 四、架构上的遗憾与改进方向

### 遗憾1：没有做自动化测试

整个项目零测试用例——全靠手动验证。随着功能增多，每次修改后回归验证的工作量越来越大。

**改进计划**：
- 核心模块（auth、rbac、resourceService）补单元测试（Jest）
- API接口补集成测试（supertest）
- CI流水线：push到仓库自动跑测试

### 遗憾2：SQLite 在高并发写入时的瓶颈

目前平台日增几十条记录，SQLite毫无压力。但如果未来扩展到全区多所学校共享，并发写入可能会成为瓶颈。

**改进方案**：
- 先尝试WAL模式 + 连接池（better-sqlite3本身支持）
- 如果还不够，迁移到PostgreSQL（better-sqlite3的API和pg的差别主要在连接方式）
- 或者考虑读写分离：主库写+多个只读副本查

### 遗憾3：前端状态管理偏原始

目前用`localStorage`存token和用户信息，组件间通信靠props/emmit。对于当前规模够用，但如果继续加功能（如实时消息通知），需要引入Pinia等状态管理方案。

### 遗憾4：日志系统缺失

出了问题只能靠`console.log`排查。应该引入结构化日志（如winston/pino），按级别分类输出到文件，方便事后追溯。

## 五、性能优化建议

| 优化项 | 当前状态 | 目标 | 方案 |
|--------|---------|------|------|
| 首页加载 | ~2s | < 1s | 接口响应加Redis缓存（或SQLite内存缓存）|
| 文件列表分页 | 每页20条 | 保持 | ✅ 已经合理 |
| PDF预览 | 前5页~3s | < 2s | 预渲染缓存 + CDN分发静态资源 |
| 大文件上传 | 500MB/10min | 支持断点续传 | 前端分片上传 + 后端合并（复杂度高，暂缓）|
| 图片压缩 | 未做 | 自动缩略图 | 上传时生成缩略图（sharp库）|
| 数据库查询 | 部分全表扫描 | 全部命中索引 | EXPLAIN ANALYZE审查慢查询 |

## 六、后续规划

### 短期（1-2个月）
- [ ] 补充核心模块单元测试
- [ ] 结构化日志接入
- [ ] 图片自动缩略图生成
- [ ] 批量操作（多选删除/批量审核）

### 中期（3-6个月）
- [ ] 消息通知系统（新资源提醒/审核结果推送）
- [ ] 数据统计图表升级（ECharts可视化）
- [ ] 资源版本管理（同一文件的多次上传保留历史）
- [ ] 移动端H5适配优化

### 长期（6个月+）
- [ ] 多租户支持（多所学校共用一套实例）
- [ ]全文检索引擎（SQLite FTS5 或集成MeiliSearch）
- [ ] 微信小程序入口（扫码直接查看/上传）
- [ ] 迁移至 PostgreSQL（如果数据量增长）

## 七、给想做类似项目的开发者的建议

如果你也想从零搭建一个类似的内部工具平台，这是我总结的7条建议：

1. **先用最简MVP跑通核心链路**——不要一上来就追求完美架构。我的第一个可用版本只有登录+上传+列表三个功能，但已经能给老师们用了。
2. **真实用户越早参与越好**——我在第10天就让几位老师试用了，他们提的问题比我自测一周发现的还多。
3. **把每次部署步骤写下来**——不管你觉得多简单，写下来。一个月后的你会感谢现在的自己。
4. **编码规范要趁早建**——哪怕只有几条"铁律"，也比没有好。它能在团队协作时避免大量沟通成本。
5. **备份策略上线第一天就要有**——不要等丢了数据才想起来。rsync定时备份+异地存储，成本极低。
6. **安全不能后补**——认证、权限校验、输入过滤，这些要在第一版就做好。后期再加安全措施的成本是初期的十倍。
7. **保持技术栈简洁**——一个人维护的项目，每多一个依赖就多一份认知负担。能用内置模块解决的就不引第三方库。

![screenshot_02_docker_containers_final.png](https://developer.qcloudimg.com/http-save/yehe-12595092/b5bf64f58708dc8c78602ec64f3278ed.png)

![screenshot_08_resources_math_clean.png](https://developer.qcloudimg.com/http-save/yehe-12595092/c4d3a5ce8549c92cf9caeda6821b5bb2.png)

![screenshot_10_admin_dashboard_clean.png](https://developer.qcloudimg.com/http-save/yehe-12595092/6f01f992e5c9e0384b04f8276bc1b55e.png)

## 八、系列完结

到这里，「从零搭建教学资源平台」系列七篇文章全部完成。


感谢阅读。如果这个系列对你有帮助，**点赞收藏**就是对我最大的支持。有问题欢迎评论区交流，我看到都会回复。

---

> 📌 **全部文章到此结束。关注我，后续会分享更多从零到一的全栈实战经验。**

**标签**：#WorkBuddy开发者分享季# #项目复盘# #全栈开发# #踩坑经验# #从零到一# #校园信息化#


写代码的时间可能只占30%，剩下的70%都在跟部署较劲。SFTP路径差异、Docker构建、容器内文件更新、端口转发……每一个环节都能卡住你半天。

# 从零搭建教学资源平台（七）：项目复盘——踩坑记录与优化建议 #WorkBuddy开发者分享季#

系列导航：本文是「从零搭建教学资源平台」系列的收官之作。前六篇我们依次讲了需求分析、技术选型、数据库设计、用户认证、文件上传、权限控制。本篇做一次全面复盘。

后端

运维

职业发展

Vue+Node教学资源平台开发全记录：6周完成18个组件+30个服务文件，经历20次版本迭代。分享15个典型Bug解决方案，包括helmet白屏、Docker构建失败等。总结NAS部署5大经验，强调部署文档和编码规范的重要性。提供SQLite优化、前端状态管理等改进方向，适合全栈开发者参考。#全栈开发 #项目复盘 #Vue #Node #教学平台

单元测试

代码解释

图片压缩

集成测试

PostgreSQL

WorkBuddy 

中间件

数据库

服务器

路由

SQLite

容器

Linux

Redis

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

CDN免费试用


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

Vue+Node教学资源平台开发全记录：6周完成18个组件+30个服务文件，经历20次版本迭代。分享15个典型Bug解决方案，包括helmet白屏、Docker构建失败等。总结NAS部署5大经验，强调部署文档和编码规范的重要性。提供SQLite优化、前端状态管理等改进方向，适合全栈开发者参考。#全栈开发 #项目复盘 #...

# 从零搭建教学资源平台（七）：项目复盘——踩坑记录与优化建议 #WorkBuddy开发者分享季#-腾讯云开发者社区-腾讯云

# 从零搭建教学资源平台（七）：项目复盘——踩坑记录与优化建议 #WorkBuddy开发者分享季#

# 从零搭建教学资源平台（七）：项目复盘——踩坑记录与优化建议 #WorkBuddy开发者分享季#

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐