1. 为什么选择HedgeDoc搭建私有Markdown协作平台第一次接触HedgeDoc是在去年帮创业团队搭建知识库的时候。当时试用了市面上七八款协作工具不是功能太复杂就是需要付费订阅。直到发现这个开源自托管的Markdown编辑器才真正解决了我们的痛点——既想要简洁的写作体验又需要实时协作能力。HedgeDoc最吸引我的三个特点是零学习成本任何会用Markdown的人都能立即上手实时协作多人编辑时能看到彼此的光标位置和修改内容完全可控数据完全掌握在自己服务器上我团队现在用它来做需求文档编写、会议记录共享甚至技术方案评审。最惊喜的是发现它还能导出PDF和幻灯片产品经理直接用它做需求宣讲。相比Notion这类SaaS工具自托管版本不用担心突然被墙也不用纠结订阅费用特别适合10人以内的小团队。2. 部署前的环境准备2.1 硬件与系统要求实测在2核CPU/2GB内存的云服务器上就能流畅运行。我的开发环境是一台闲置的Intel NUC小主机i5-8259U/8GB内存跑Docker版HedgeDoc同时开十几个文档都不卡顿。操作系统推荐Ubuntu 22.04 LTS或CentOS 7这两个系统我都部署成功过。注意如果选择ARM架构设备比如树莓派需要确认Docker镜像是否提供ARM版本2.2 数据库选型建议HedgeDoc支持MariaDB和PostgreSQL两种数据库。我两种都试过给出些实用建议MariaDB 10.3资源占用低适合轻量级部署PostgreSQL 12对复杂查询支持更好适合文档量大的场景在阿里云学生机上测试同样配置下PostgreSQL的并发处理能力确实更强。但如果是个人使用MariaDB完全够用还省资源。记得提前创建好空数据库我习惯命名为hedgedoc_db。3. Docker部署全流程详解3.1 镜像选择与下载官方推荐使用linuxserver/hedgedoc镜像我对比过三个常见镜像的差异镜像名称更新频率体积特色linuxserver/hedgedoc每周更新350MB集成健康检查hedgedoc/hedgedoc每月更新280MB官方原版bitnami/hedgedoc不定期410MB包含全套监控建议用这个命令拉取最新镜像docker pull linuxserver/hedgedoc:latest3.2 目录结构与权限配置我的标准目录结构是这样的/opt/hedgedoc ├── config/ # 配置文件 ├── uploads/ # 图片等附件 └── db-backup/ # 数据库备份关键是要给目录正确赋权mkdir -p /opt/hedgedoc/{config,uploads,db-backup} chown -R 1000:1000 /opt/hedgedoc3.3 环境变量配置技巧这是最容易踩坑的部分。分享我的生产环境配置模板-e DB_HOST127.0.0.1 \ -e DB_PORT3306 \ -e DB_NAMEhedgedoc_db \ -e DB_USERhedgedoc_user \ -e DB_PASSStrongPassword!123 \ -e CMD_PORT8080 \ -e CMD_DOMAINdocs.yourdomain.com \ -e CMD_PROTOCOL_USESSLtrue \ -e CMD_URL_ADDPORTfalse \特别注意密码建议用单引号包裹避免特殊字符被解析如果走HTTPS访问必须设置CMD_PROTOCOL_USESSLtrue对外访问域名不要带端口号时CMD_URL_ADDPORTfalse4. 安全加固与性能调优4.1 必做的安全设置上周帮客户排查入侵事件时发现很多人在基础安全上疏忽。这几个设置务必检查修改默认管理员邮箱在config目录的production.json中添加email: your-admindomain.com启用访问限制限制注册权限allowRegister: false配置定期备份我的备份脚本# 每天3点备份数据库 0 3 * * * docker exec hedgedoc_db mysqldump -u root -p密码 hedgedoc_db /backups/hedgedoc_$(date \%Y\%m\%d).sql4.2 性能优化实战当文档超过500个时我遇到了加载缓慢问题。通过这三步优化将响应时间从3s降到800ms数据库索引优化CREATE INDEX idx_notes_title ON notes(title); CREATE INDEX idx_revisions_noteId ON revisions(noteId);调整Node.js内存限制在Docker启动命令添加-e NODE_OPTIONS--max-old-space-size2048启用文档缓存修改config.jsoncaching: { enabled: true, duration: 3600000 }5. 日常维护与故障排查5.1 版本升级指南上个月升级1.9.2版本时遇到插件兼容问题总结出安全升级步骤先备份数据库和config目录停止旧容器但不删除拉取新镜像创建测试容器用--entrypoint sh进入容器检查日志确认无误后再迁移正式数据5.2 常见问题解决方案问题1启动后一直显示Im busy right now检查数据库连接参数查看日志是否有Connection refused错误我遇到的情况是防火墙挡住了3306端口问题2上传图片失败确认uploads目录有写入权限检查nginx反代配置是否有client_max_body_size限制我的解决方案是设置client_max_body_size 20M;问题3协作时修改不同步检查CMD_DOMAIN是否配置正确可能是WebSocket连接问题需要配置nginx支持ws协议我的nginx配置片段location / { proxy_pass http://localhost:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; }这套部署方案已经在三个创业团队稳定运行半年多。最让我意外的是原本只是用来写技术文档现在连运营部门都在用它做内容协作。有个实用技巧配合Git钩子可以实现文档自动同步到代码仓库实现真正的版本控制。