HedgeDoc 协作笔记平台搭建教程

HedgeDoc（前身为 CodiMD）是一款开源的实时协作 Markdown 笔记平台，支持多人同时编辑同一份文档。它非常适合团队协作、会议记录、知识库管理等场景。本文将详细介绍如何在搬瓦工 VPS 上通过 Docker 部署 HedgeDoc，并完成反向代理和基础配置。如果你还没有安装 Docker，请先参考 Docker 安装教程。

一、HedgeDoc 功能特点

HedgeDoc 作为一款成熟的协作笔记工具，具备以下核心功能：

实时协作：多个用户可以同时编辑同一篇文档，所有修改实时同步显示。
Markdown 支持：完整支持 Markdown 语法，包括表格、代码高亮、数学公式（KaTeX/MathJax）等。
幻灯片模式：支持将 Markdown 文档转换为幻灯片演示，方便做简报。
权限控制：文档可设置为公开、登录可见或私有，灵活控制访问权限。
多种登录方式：支持本地账号、LDAP、OAuth（GitHub、GitLab 等）多种认证方式。
历史版本：自动保存文档修改历史，可以回溯到任意版本。
图片上传：支持粘贴或拖拽上传图片，可配置存储到本地或 S3。

二、环境要求与准备

在开始部署之前，请确认满足以下条件：

搬瓦工 VPS 一台，建议内存 1GB 以上（推荐购买时使用优惠码 NODESEEK2026 享受 6.77% 折扣）。
已安装 Docker 和 Docker Compose（参考 Docker 安装教程）。
一个已解析到 VPS IP 的域名（可选但推荐）。
系统推荐 Ubuntu 22.04 或 Debian 12。

2.1 创建项目目录

mkdir -p /opt/hedgedoc
cd /opt/hedgedoc

三、编写 Docker Compose 配置

HedgeDoc 需要搭配 PostgreSQL 数据库使用。创建 docker-compose.yml 文件：

cat > /opt/hedgedoc/docker-compose.yml <<'EOF'
version: '3.8'

services:
  database:
    image: postgres:15-alpine
    restart: always
    environment:
      POSTGRES_USER: hedgedoc
      POSTGRES_PASSWORD: your_db_password_here
      POSTGRES_DB: hedgedoc
    volumes:
      - db_data:/var/lib/postgresql/data

  hedgedoc:
    image: quay.io/hedgedoc/hedgedoc:latest
    restart: always
    depends_on:
      - database
    ports:
      - "3000:3000"
    environment:
      CMD_DB_URL: postgres://hedgedoc:your_db_password_here@database:5432/hedgedoc
      CMD_DOMAIN: notes.yourdomain.com
      CMD_PROTOCOL_USESSL: "true"
      CMD_URL_ADDPORT: "false"
      CMD_ALLOW_ANONYMOUS: "false"
      CMD_ALLOW_EMAIL_REGISTER: "true"
      CMD_IMAGE_UPLOAD_TYPE: filesystem
      CMD_SESSION_SECRET: your_random_session_secret_here
    volumes:
      - upload_data:/hedgedoc/public/uploads

volumes:
  db_data:
  upload_data:
EOF

重要：请将 your_db_password_here 替换为强密码，将 notes.yourdomain.com 替换为你的实际域名，并生成随机的 session secret。

3.1 生成随机密钥

openssl rand -hex 32

将输出结果填入 CMD_SESSION_SECRET 的值中。

四、启动 HedgeDoc

cd /opt/hedgedoc
docker compose up -d

等待镜像下载完成后，检查服务状态：

docker compose ps

确认两个容器均为 running 状态。此时 HedgeDoc 已在端口 3000 上运行。

五、配置 Nginx 反向代理

为了通过域名和 HTTPS 访问 HedgeDoc，建议配置 Nginx 反向代理。

5.1 安装 Nginx 和 Certbot

apt update
apt install nginx certbot python3-certbot-nginx -y

5.2 创建 Nginx 配置

cat > /etc/nginx/sites-available/hedgedoc <<'EOF'
server {
    listen 80;
    server_name notes.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }

    # WebSocket 支持（实时协作必需）
    location /socket.io/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }

    client_max_body_size 50m;
}
EOF

ln -sf /etc/nginx/sites-available/hedgedoc /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

5.3 申请 SSL 证书

certbot --nginx -d notes.yourdomain.com

按照提示完成证书申请，Certbot 会自动修改 Nginx 配置并启用 HTTPS。

六、HedgeDoc 常用配置

6.1 禁止匿名访问

在 docker-compose.yml 中设置：

CMD_ALLOW_ANONYMOUS: "false"
CMD_ALLOW_ANONYMOUS_EDITS: "false"

6.2 配置 GitHub OAuth 登录

在 GitHub 上创建 OAuth Application 后，添加以下环境变量：

CMD_GITHUB_CLIENTID: your_github_client_id
CMD_GITHUB_CLIENTSECRET: your_github_client_secret

6.3 限制注册

如果只希望特定用户使用，可以关闭邮箱注册：

CMD_ALLOW_EMAIL_REGISTER: "false"

七、数据备份

定期备份数据库和上传文件是非常重要的：

7.1 备份数据库

docker compose exec database pg_dump -U hedgedoc hedgedoc > /opt/hedgedoc/backup_$(date +%Y%m%d).sql

7.2 备份上传文件

docker cp $(docker compose ps -q hedgedoc):/hedgedoc/public/uploads /opt/hedgedoc/uploads_backup

7.3 自动备份脚本

cat > /opt/hedgedoc/backup.sh <<'SCRIPT'
#!/bin/bash
BACKUP_DIR="/opt/hedgedoc/backups"
mkdir -p $BACKUP_DIR
cd /opt/hedgedoc
docker compose exec -T database pg_dump -U hedgedoc hedgedoc > $BACKUP_DIR/db_$(date +%Y%m%d).sql
find $BACKUP_DIR -name "*.sql" -mtime +7 -delete
SCRIPT
chmod +x /opt/hedgedoc/backup.sh

添加 crontab 定时任务，每天凌晨 3 点执行备份：

echo "0 3 * * * /opt/hedgedoc/backup.sh" | crontab -

八、版本更新

更新 HedgeDoc 到最新版本：

cd /opt/hedgedoc
docker compose pull
docker compose up -d
docker image prune -f

建议更新前先执行数据备份操作。

九、常见问题

WebSocket 连接失败

如果实时协作功能不工作，检查 Nginx 是否正确配置了 WebSocket 代理。确保 location /socket.io/ 部分包含 Upgrade 和 Connection 头。

图片上传失败

检查上传目录的权限：

docker compose exec hedgedoc ls -la /hedgedoc/public/uploads

如果权限不正确，可以在容器内修正：

docker compose exec hedgedoc chown -R hedgedoc:hedgedoc /hedgedoc/public/uploads

数据库连接错误

确认数据库容器正常运行，并检查连接字符串中的用户名密码是否一致：

docker compose logs database

总结

HedgeDoc 是一个功能完善的协作笔记平台，通过 Docker 部署在搬瓦工 VPS 上非常方便。它的实时协作能力和丰富的 Markdown 支持使其成为团队知识管理的好选择。你还可以在 VPS 上部署 Nextcloud 云盘、Gitea 代码仓库等服务，打造完整的自托管工作环境。选购搬瓦工 VPS 请访问 bwh81.net，购买时使用优惠码 NODESEEK2026 可享受 6.77% 优惠。