HedgeDoc环境变量配置全解析：从CMD_PORT到DB_HOST，教你搞定群晖Docker部署中最容易出错的环节
当你第一次在群晖Docker中部署HedgeDoc时，看到屏幕上出现"I'm busy right now"的提示，或者根本无法访问服务界面，这种挫败感我深有体会。作为一个经历过无数次部署失败的老手，我明白问题的核心往往不在于操作步骤本身，而在于那些看似简单却暗藏玄机的环境变量配置。本文将带你深入理解HedgeDoc的配置逻辑，避开那些让我踩过坑的陷阱。
1. 环境变量基础：理解HedgeDoc的配置骨架
HedgeDoc的灵活性来自于其丰富的环境变量配置选项，这也是最容易出错的地方。在群晖Docker中，这些变量构成了应用与运行环境之间的桥梁。我们需要先理解几个关键概念：
- 数据库连接变量组：
DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASS - 服务端口变量：
CMD_PORT（最常被忽视的关键变量） - URL构建变量组：
CMD_DOMAIN、CMD_URL_ADDPORT、CMD_PROTOCOL_USESSL - 系统变量：
PGID、PUID、TZ
这些变量不是孤立存在的，它们之间存在复杂的依赖关系。比如，CMD_PORT的错误设置会影响CMD_URL_ADDPORT的行为，而DB_HOST的格式错误会导致整个数据库连接失败。
1.1 数据库连接：90%部署失败的罪魁祸首
数据库配置错误是HedgeDoc部署失败的首要原因。以下是一个典型的正确配置示例：
environment: - DB_HOST=192.168.1.100 # 数据库服务器IP - DB_PORT=3306 # MariaDB默认端口 - DB_NAME=hedgedoc # 预先创建的数据库名 - DB_USER=hedgedoc_user # 有权限的用户 - DB_PASS=securepassword # 强密码常见错误及解决方案：
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| "Can't connect to MySQL server" | DB_HOST使用容器名而非IP | 使用宿主机IP或Docker网络IP |
| "Access denied for user" | DB_USER权限不足 | 确保用户有数据库的完全权限 |
| "Unknown database" | DB_NAME未预先创建 | 先在MariaDB中创建空数据库 |
| 连接超时 | DB_PORT与实际端口不符 | 确认数据库服务监听端口 |
提示：在群晖环境中，如果使用内置MariaDB，
DB_HOST应该是群晖主机的局域网IP，而不是localhost或127.0.0.1，因为Docker容器被视为独立主机。
2. 端口配置的艺术：为什么你的服务无法访问
端口配置看似简单，实则暗藏玄机。HedgeDoc涉及两个层面的端口设置：
- Docker端口映射：如
3070:3000（主机端口:容器端口） - 应用内部端口：通过
CMD_PORT指定
2.1 CMD_PORT的陷阱
CMD_PORT是最容易被误解的变量之一。它决定了HedgeDoc应用内部监听的端口，必须与Docker端口映射的右侧值一致。例如：
ports: - "3070:3070" # 主机端口:容器端口 environment: - CMD_PORT=3070 # 必须与容器端口一致典型错误场景：
- 使用默认端口3000但未设置
CMD_PORT=3000 - 在反向代理后仍保留端口号导致URL构建错误
- 忘记群晖防火墙需要开放相应端口
2.2 URL构建三剑客：DOMAIN、ADDPORT、USESSL
这三个变量共同决定了HedgeDoc如何生成各种链接：
environment: - CMD_DOMAIN=docs.yourdomain.com # 无协议前缀 - CMD_URL_ADDPORT=false # 使用80/443时设为false - CMD_PROTOCOL_USESSL=true # 使用HTTPS时设为true配置组合示例：
| 场景 | CMD_DOMAIN | CMD_URL_ADDPORT | CMD_PROTOCOL_USESSL |
|---|---|---|---|
| 直接IP访问 | 192.168.1.100 | true | false |
| 域名+非标准端口 | example.com | true | false |
| HTTPS标准端口 | example.com | false | true |
| HTTP标准端口 | example.com | false | false |
3. 高级配置与故障排查
3.1 用户与权限：PGID和PUID的奥秘
在Docker中，这些设置决定了文件权限：
environment: - PGID=1000 # 通常与群晖管理用户组一致 - PUID=1000 # 通常与群晖管理用户ID一致获取正确值的方法：
# 在群晖SSH中执行 id [你的管理员用户名]3.2 时区设置：不只是Asia/Shanghai
虽然TZ=Asia/Shanghai适用于中国用户，但更规范的写法是：
environment: - TZ=Etc/UTC # 国际标准时间 # 或 - TZ=Asia/Taipei # 更精确的时区3.3 日志分析：找出"I'm busy"背后的真相
当服务无法访问时，查看日志是第一步：
docker logs hedgedoc # 查看容器日志常见日志模式与解决方案：
数据库连接问题：
ERROR: connect ECONNREFUSED检查
DB_HOST和DB_PORT是否正确端口冲突：
Error: listen EADDRINUSE更改
CMD_PORT和映射端口权限问题：
EACCES: permission denied检查
/config目录权限和PGID/PUID设置
4. 完整配置示例与最佳实践
4.1 Docker Compose全配置模板
version: "3" services: hedgedoc: image: linuxserver/hedgedoc container_name: hedgedoc restart: unless-stopped ports: - "3080:3080" # 避免使用3000/80/443 volumes: - ./config:/config environment: # 数据库配置 - DB_HOST=192.168.1.100 - DB_PORT=3306 - DB_NAME=hedgedoc - DB_USER=hedgedoc_user - DB_PASS=your_strong_password # 系统配置 - PGID=1000 - PUID=1000 - TZ=Asia/Shanghai # 服务配置 - CMD_DOMAIN=your.domain.com - CMD_URL_ADDPORT=false - CMD_PROTOCOL_USESSL=true - CMD_PORT=30804.2 分阶段验证法
基础验证：
- 确保
docker ps显示容器状态为"Up" - 检查日志无ERROR级别记录
- 确保
数据库验证：
docker exec -it hedgedoc bash # 在容器内测试数据库连接 mysql -h$DB_HOST -P$DB_PORT -u$DB_USER -p$DB_PASS $DB_NAME -e "SELECT 1"服务验证：
curl -v http://localhost:3080 # 替换为你的端口前端验证：
- 浏览器访问应显示登录界面
- 检查开发者工具控制台无资源加载错误
4.3 性能调优参数（可选）
对于高负载环境，可添加：
environment: - CMD_MAX_BODY_SIZE=10mb # 上传大小限制 - CMD_IMAGE_UPLOAD_TYPE=filesystem # 图片存储方式 - CMD_DOMAIN_SOCKET=/tmp/hedgedoc.sock # Unix域套接字记住，每个HedgeDoc部署场景都是独特的。在我最近一次为客户部署时，就因为CMD_URL_ADDPORT在反向代理环境中的错误设置，导致花了3小时排查。关键是要理解每个变量的实际作用，而不是盲目复制配置。
