CodiMD/HackMD Docker Compose 部署指南

概述

CodiMD/HackMD 是一款开源的协作式 Markdown 编辑器，支持多人实时协作编辑文档。本文将通过 Docker Compose 方式详细介绍如何部署 CodiMD/HackMD 服务，帮助开发者快速搭建自己的协作笔记平台。

环境准备

在开始部署前，请确保系统已安装以下组件：

• Docker 18.06+
• Docker Compose 1.22+

服务架构解析

该 Docker Compose 文件定义了两个核心服务：

1. 数据库服务：使用 PostgreSQL 11.6 Alpine 版本作为数据存储
2. 应用服务：运行 CodiMD/HackMD 2.5.3 版本

详细配置说明

数据库服务配置

database:
  image: postgres:11.6-alpine
  environment:
    - POSTGRES_USER=codimd
    - POSTGRES_PASSWORD=change_password
    - POSTGRES_DB=codimd
  volumes:
    - "database-data:/var/lib/postgresql/data"
  restart: always

关键点说明：

• 使用轻量级的 Alpine 版本 PostgreSQL 镜像
• 默认用户名为 codimd，密码为 change_password（生产环境必须修改）
• 数据库名称为 codimd
• 通过卷挂载实现数据持久化
• 设置自动重启策略确保服务高可用

应用服务配置

codimd:
  image: nabo.codimd.dev/hackmdio/hackmd:2.5.3
  environment:
    - CMD_DB_URL=postgres://codimd:change_password@database/codimd
    - CMD_USECDN=false
  depends_on:
    - database
  ports:
    - "3000:3000"
  volumes:
    - upload-data:/home/hackmd/app/public/uploads
  restart: always

关键点说明：

• 使用官方 2.5.3 版本镜像
• 通过环境变量配置数据库连接（需与数据库服务配置一致）
• 禁用 CDN 资源加载（适合内网部署）
• 声明依赖关系确保数据库先启动
• 映射 3000 端口到主机
• 上传目录通过卷挂载实现持久化
• 设置自动重启策略

数据持久化方案

该配置通过 Docker 卷实现了两个关键数据的持久化：

1. database-data：存储 PostgreSQL 数据库文件
2. upload-data：存储用户上传的文件

这种设计确保了即使容器重启，数据也不会丢失。

部署步骤

1. 创建 docker-compose.yml 文件并填入上述内容
2. 修改默认密码（强烈建议）
3. 执行部署命令：

   docker-compose up -d
   

4. 等待服务启动完成后，访问 http://localhost:3000

自定义构建选项

配置文件中提供了自定义构建的注释选项，如需使用：

1. 取消注释 build 部分
2. 确保已准备好构建环境
3. 使用以下命令构建并启动：

   docker-compose -f docker-compose.yml up --build
   

安全建议

1. 修改默认密码：必须修改数据库和应用中的默认密码
2. 启用 HTTPS：生产环境应配置反向代理并启用 HTTPS
3. 定期备份：定期备份数据库卷和上传目录
4. 访问控制：考虑配置身份验证机制

常见问题排查

1. 端口冲突：确保主机 3000 端口未被占用
2. 数据库连接失败：检查数据库服务是否正常启动
3. 权限问题：确保 Docker 有足够的权限创建卷
4. 资源不足：如遇性能问题，可考虑增加资源限制

通过以上配置和说明，您应该能够成功部署一个功能完整的 CodiMD/HackMD 协作平台。根据实际需求，您还可以进一步调整配置参数以优化性能和安全性。