Tasks.md 3.3.0 Docker Compose 部署指南

用 Docker Compose 部署 Tasks.md 3.3.0 官方镜像：编排文件、数据持久化、环境变量、主题切换、等价 docker run 与运维命令，全部实测验证。

Tasks.mdTasks.mdDockerDocker Compose自托管2026/10/25

Tasks.md 3.3.0 Docker Compose 部署指南

目标：用 Docker Compose 一键部署官方镜像 baldissaramatheus/tasks.md:3.3.0，完成数据持久化、环境变量配置与运维验证。本文所有命令与回显均已在实测环境（Docker Engine + Compose v2，端口 8134）验证通过。

一、环境信息

  • 宿主机：Linux x86_64，已安装 Docker Engine 与 Docker Compose v2（docker compose version 可用）
  • 镜像：baldissaramatheus/tasks.md:3.3.0（Docker Hub 官方镜像，2026-03-08 构建，拉取后体积约 632 MB）
  • 编排项目名：tasks-md-330-stack（compose name: 字段不允许小数点，故版本号去点）
  • 端口映射：宿主 8134 → 容器 8080（读者可换成任意空闲端口）
  • 数据目录（bind mount）：./data/tasks → /tasks，./data/config → /config

⚠️ 网络说明：实测时 Docker Hub 官方源拉取缓慢，已通过 registry 镜像加速器完成拉取；读者若拉取超时，可配置镜像加速或代理后重试。

二、镜像选型说明

Docker Hub 上 baldissaramatheus/tasks.md 的标签策略（2026-10-25 查询）：

标签指向说明
3.3.0固定版本本文采用，可复现、可回滚
3.3 / 3滚动跟随最新 3.3.x / 3.x自动跟进补丁版
latest滚动跟随最新稳定版不建议生产使用，升级不可预期

选择建议：生产环境锁定完整版本号（3.3.0）；测试环境可用 3 自动跟进补丁。

三、前置条件

docker --version
docker compose version

确认 Docker 守护进程运行中：docker info 无报错即可。本文以 root 直接执行演示；普通用户需在 docker 用户组中。

四、部署步骤

4.1 准备项目目录与编排文件

mkdir -p /opt/tasks-md/data/tasks /opt/tasks-md/data/config
cd /opt/tasks-md

创建 docker-compose.yml：

name: tasks-md-330-stack
services:
  tasks-md:
    image: baldissaramatheus/tasks.md:3.3.0
    container_name: tasks-md-3.3.0-app
    environment:
      - PUID=1000
      - PGID=1000
      - TITLE=Tasks.md 演示看板
      - BASE_PATH=
      - LOCAL_IMAGES_CLEANUP_INTERVAL=1440
    volumes:
      - /opt/tasks-md/data/tasks:/tasks
      - /opt/tasks-md/data/config:/config
    ports:
      - "8134:8080"
    restart: unless-stopped

⚠️ 注意：compose 顶层 name:（项目名）只允许小写字母、数字、连字符与下划线，不能含小数点，因此写作 tasks-md-330-stack 而非 tasks-md-3.3.0-stack。

4.2 启动栈

cd /opt/tasks-md
docker compose up -d

实测回显：

 Container tasks-md-3.3.0-app Running

首次启动时镜像会在容器内执行前端构建（vite build），日志可见：

> tasks.md@0.0.0 build
> vite build --base=/
vite v5.4.19 building for production...
...
API starting at 8080

4.3 验证部署

docker compose ps
curl -s http://localhost:8134/_api/title
curl -s -o /dev/null -w "GET / -> %{http_code}\n" http://localhost:8134/

实测回显：

NAME                 IMAGE                              COMMAND                  SERVICE    CREATED              STATUS              PORTS
tasks-md-3.3.0-app   baldissaramatheus/tasks.md:3.3.0   "/bin/sh -c 'sh entr…"   tasks-md   About a minute ago   Up About a minute   0.0.0.0:8134->8080/tcp, [::]:8134->8080/tcp
Tasks.md 演示看板
GET / -> 200

浏览器访问 http://<服务器IP>:8134 即可打开看板。

五、数据持久化说明

Tasks.md 的全部数据都在两个卷里：

容器路径内容本文宿主路径
/tasks泳道目录 + 卡片 Markdown 文件./data/tasks
/config主题样式、标签颜色（tags.json）、排序（sort.json）、上传图片（images/）./data/config

实测：通过 API 创建泳道「待办」与卡片「部署验证.md」后，宿主目录即时可见：

/opt/tasks-md/data/:
config
tasks

/opt/tasks-md/data/config:
images
sort
stylesheets

/opt/tasks-md/data/tasks:
待办

/opt/tasks-md/data/tasks/待办:
部署验证.md

重启验证数据不丢：

docker compose restart
curl -s http://localhost:8134/_api/resource/

实测回显：

[{"name":"待办","files":[{"name":"部署验证","content":"## Compose 部署验证\n\n- [x] 数据持久化\n","lastUpdated":"2026-10-25T01:36:44.506Z","createdAt":"2026-10-25T01:36:44.506Z"}]}]

卡片内容与文件时间戳均在重启后保持不变。

💡 说明：PUID/PGID 决定容器内新建文件的属主。设为 1000:1000 时，宿主机上 ./data 下新文件归属于 UID/GID 1000 的用户，便于宿主机直接用编辑器改任务文件；不设则为 root 所有。

六、环境变量表

变量默认值必填说明
PUID无建议新建文件属主 UID
PGID无必填配对新建文件属主 GID
TITLE空否页面与浏览器标签页标题
BASE_PATH空否子路径反代基础路径（如 /tasks）；置非 / 时 PWA 不可用
LOCAL_IMAGES_CLEANUP_INTERVAL1440否未引用图片清理周期（分钟），0 关闭

参数语义与逐项说明见本专栏《Tasks.md 3.3.0 配置参数详解》篇。

七、配置参数说明

容器启动时 entrypoint 会完成三件事：

  1. 若 CONFIG_DIR/stylesheets/custom.css 不存在，写入默认内容（导入 adwaita 主题）；
  2. 按 BASE_PATH 重新构建前端并把产物复制为后端静态目录；
  3. 若设置了 PUID/PGID，对 /tasks 与 /config 递归 chown。

因此：修改 BASE_PATH、TITLE 等变量后 docker compose up -d 重建容器即可；样式文件 custom.css 改宿主 ./data/config/stylesheets/custom.css 即时生效，无需重启。

切换主题示例（改宿主文件）：

echo "@import url(./color-themes/nord.css);" > /opt/tasks-md/data/config/stylesheets/custom.css
curl -s http://localhost:8134/stylesheets/custom.css

实测回显：

@import url(./color-themes/nord.css);

八、配置文件挂载

除环境变量外，常用挂载点：

宿主文件/目录容器路径用途
./data/config/stylesheets/custom.css/config/stylesheets/custom.css自定义样式入口
./data/config/stylesheets/color-themes//config/stylesheets/color-themes/内置三套主题（adwaita/nord/catppuccin），可增删
./data/config/tags.json/config/tags.json标签颜色映射（应用自动维护）
./data/config/sort.json/config/sort.json卡片排序（应用自动维护）

九、等价 docker run

不使用 Compose 时，与本文编排等价的单命令：

docker run -d \
  --name tasks-md-3.3.0-app \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TITLE="Tasks.md 演示看板" \
  -e BASE_PATH= \
  -e LOCAL_IMAGES_CLEANUP_INTERVAL=1440 \
  -p 8134:8080 \
  -v /opt/tasks-md/data/tasks:/tasks \
  -v /opt/tasks-md/data/config:/config \
  --restart unless-stopped \
  baldissaramatheus/tasks.md:3.3.0

十、常用运维命令

docker compose ps              # 查看栈内服务状态
docker compose logs -f         # 跟踪日志
docker compose restart         # 重启服务
docker compose down            # 停止并删除栈（数据卷保留）
docker compose up -d           # 重新启动栈
docker compose pull            # 拉取编排中声明的镜像新版本

升级版本流程：改 docker-compose.yml 中 image: 为新版本号 → docker compose pull → docker compose up -d → curl -s http://localhost:8134/_api/title 验证。

⚠️ 注意：从 2.x 升级到 3.x 需先按官方 migration-guide 处理（环境变量与目录结构有变化），跨大版本升级前务必备份 ./data。

十一、常见问题

Q1：docker compose up -d 报项目名非法？ name: 含小数点等大写/特殊字符所致。compose 项目名只允许 [a-z0-9_-]，用 tasks-md-330-stack 这类写法。

Q2：启动后浏览器访问空白？ 首次启动容器内要跑前端构建（日志有 vite build），大内存机器数秒即可完成；若日志停在构建阶段较久属正常，等到出现 API starting at 8080 再访问。

Q3：页面标题没有变成 TITLE 的值？ TITLE 在进程启动时读取。改完执行 docker compose up -d（重建容器）而非仅 restart，并强制刷新浏览器缓存。

Q4：上传的图片过几天不见了？ LOCAL_IMAGES_CLEANUP_INTERVAL 默认 1440 分钟清理未被引用的图片。确认卡片正文中图片引用形如 ![描述](_api/image/<文件名>)；或将该变量置 0 关闭清理。

Q5：中文泳道/卡片通过 API 操作异常？ API 路径中的中文必须 percent-encode，详见本专栏《Tasks.md 3.3.0 API 使用详解》篇排障实录。

Q6：反代到子路径后静态资源 404？ BASE_PATH 必须与反代路径一致（如都设为 /tasks），改 BASE_PATH 后需 docker compose up -d 让 entrypoint 重新构建前端产物。

十二、参考链接