Tasks.md 3.3.0 配置参数详解

Tasks.md 3.3.0 全部配置入口实测详解：环境变量、CONFIG_DIR 各文件、主题与颜色变量、BASE_PATH 反代、图片清理策略与生产配置模板。

Tasks.mdTasks.md任务管理自托管Node.js2026/10/25

Tasks.md 3.3.0 配置参数详解

目标：系统讲解 Tasks.md 3.3.0 的全部配置入口——环境变量、配置目录（custom.css / tags.json / sort.json / images）、主题与颜色变量、反向代理子路径、图片清理策略，并给出生产配置模板。本文基于 Ubuntu 22.04 源码安装环境（安装过程见《Ubuntu 22.04 安装 Tasks.md 3.3.0 指南》）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • 组件版本：Tasks.md 3.3.0
  • 运行时：Node.js 18.20.8
  • 源码目录：/opt/tasks-md；数据目录：/opt/tasks-md-data（tasks/ + config/）
  • 托管方式：systemd 单元 tasks-md.service，环境变量在单元文件中配置
  • 服务端口：8080

二、前置条件

已按本专栏《Ubuntu 22.04 安装 Tasks.md 3.3.0 指南》完成安装并通过 systemctl is-active tasks-md 返回 active 验证。本文所有配置修改后的验证命令均假设服务监听本机 8080 端口。

查看当前服务状态：

systemctl is-active tasks-md

实测回显：

active

三、参数查看与修改方式

Tasks.md 没有传统意义上的配置文件，配置分两类：

  1. 环境变量：进程启动时读取，决定端口、目录、标题、子路径、清理周期等运行参数。修改入口是 systemd 单元文件 /etc/systemd/system/tasks-md.service 中的 Environment= 行，改后必须：
systemctl daemon-reload
systemctl restart tasks-md
  1. 配置目录文件：CONFIG_DIR 下的 stylesheets/custom.css、tags.json、sort.json、images/。这类文件即时生效、无需重启——后端在每次请求时实时读取（实测：改完 custom.css 立即 curl http://localhost:8080/stylesheets/custom.css 即返回新内容）。

四、参数总览

全部环境变量及其在源码（backend/server.js）中的默认值：

环境变量默认值类型说明
PORT8080整数HTTP 监听端口
CONFIG_DIRconfig（相对后端工作目录）路径配置目录：样式、标签、排序、图片
TASKS_DIRtasks（相对后端工作目录）路径任务数据目录：泳道目录与卡片 .md 文件
TITLE空字符串字符串页面标题栏与浏览器标签页标题
BASE_PATH空字符串路径串子路径反代的基础路径；/ 会被归一化为空
LOCAL_IMAGES_CLEANUP_INTERVAL1440（分钟）非负整数未引用本地图片的自动清理周期；0 关闭
PUID0整数新建任务文件/目录 chown 的目标 UID
PGID0整数新建任务文件/目录 chown 的目标 GID

💡 说明：PUID/PGID 同时为 0（默认）时后端不做任何 chown，文件属主跟随运行进程的用户；只有两者都非 0 且进程有权限（如 root 运行）时才会对新建资源执行 chown。

五、核心参数分类详解

5.1 监听与路径类（PORT / CONFIG_DIR / TASKS_DIR / BASE_PATH）

PORT：修改端口示例——把服务改到 9090：

Environment="PORT=9090"

daemon-reload + restart 后验证：

ss -ltnp | grep 9090

CONFIG_DIR / TASKS_DIR：建议使用绝对路径（如 /opt/tasks-md-data/config、/opt/tasks-md-data/tasks）。使用相对路径时会相对 WorkingDirectory（后端目录）解析，升级源码时容易被覆盖，生产环境务必用绝对路径。

BASE_PATH：把应用挂到子路径（如 https://example.com/tasks/）时设为 /tasks：

Environment="BASE_PATH=/tasks"
  • 后端会把 API 挂载到 /tasks/_api，页面挂载到 /tasks/；
  • 源码中 BASE_PATH="/" 会被归一化为空字符串，即根路径部署；
  • ⚠️ 官方 README 明确说明：BASE_PATH 为非 / 值时 PWA 功能不可用；
  • 反代侧（Nginx 示例）需保留原始路径转发：
location /tasks/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

5.2 标题与品牌类（TITLE）

TITLE 显示在页面头部与浏览器标签页。设置与验证：

Environment="TITLE=Tasks.md 生产看板"

systemctl daemon-reload && systemctl restart tasks-md
curl -s http://localhost:8080/_api/title

实测回显：

Tasks.md 生产看板

⚠️ 排障实录：systemd 的 Environment= 值含空格必须整体加双引号。实测写 Environment=TITLE=Tasks.md 生产看板（不加引号）时，进程拿到的值被截断为 Tasks.md，上述 curl 只返回 Tasks.md；加引号重启后返回完整标题。

5.3 文件属主类（PUID / PGID）

后端在「新建泳道/卡片/上传图片/写排序文件」时，若 PUID 与 PGID 均非 0，会执行 chown 把新文件归属到指定用户。典型场景：后端以 root 运行、但希望任务文件归属于普通用户 ubuntu（UID 1000）方便宿主机直接编辑：

Environment="PUID=1000"
Environment="PGID=1000"

UID/GID 查询命令：

id ubuntu

⚠️ 注意：服务以非 root 用户运行时，chown 会因权限不足失败（仅影响属主调整，不影响文件创建），因此 PUID/PGID 机制通常只在 root 运行的部署中使用；若以专用用户运行，保持默认 0 即可，文件自然归属该用户。

5.4 图片清理类（LOCAL_IMAGES_CLEANUP_INTERVAL）

卡片正文中可引用上传的本地图片（存于 CONFIG_DIR/images/）。后端按该周期扫描全部 .md 文件，删除不再被任何卡片引用的图片：

  • 单位：分钟；默认 1440（24 小时）；
  • 取值校验：源码用 /^\d{1,}$/ 校验，非纯数字（如 abc）会被忽略并回退到 1440；
  • 0 表示关闭自动清理；
  • 引用判定：正文中形如 ![...](..._api/image/<文件名>) 的 Markdown 图片语法。

关闭自动清理的配置：

Environment="LOCAL_IMAGES_CLEANUP_INTERVAL=0"

⚠️ 注意：只有引用路径包含 _api/image/ 的图片才被识别为「使用中」；用其他方式引用 images/ 下文件的写法会被误删，自定义引用前请先关闭清理或改走外部图床。

5.5 配置目录文件详解（custom.css / tags.json / sort.json / images）

实测配置目录结构：

/opt/tasks-md-data/config
/opt/tasks-md-data/config/images
/opt/tasks-md-data/config/images/ecb83ad8-ffda-4ca7-8385-e6fd45d64bc9.png
/opt/tasks-md-data/config/sort
/opt/tasks-md-data/config/sort.json
/opt/tasks-md-data/config/stylesheets
/opt/tasks-md-data/config/stylesheets/color-themes
/opt/tasks-md-data/config/stylesheets/custom.css
/opt/tasks-md-data/config/tags.json

各文件作用：

文件/目录作用写入时机
stylesheets/custom.css自定义样式入口，默认导入 adwaita 主题手工编辑
stylesheets/color-themes/内置三套主题：adwaita.css、nord.css、catppuccin.css部署时从静态产物复制
tags.json标签名 → 颜色变量 的映射（按项目路径分组）界面/API 修改标签颜色时
sort.json泳道内卡片排序数据（按项目路径分组）拖拽排序时
images/卡片上传的本地图片（UUID 文件名）上传图片时
sort/预留目录（当前版本排序数据实际写 sort.json）启动时创建

实测 tags.json 内容（根项目下设置了 bug / 需求 两个标签颜色）：

{"/":{"bug":"var(--color-alt-1)","需求":"var(--color-alt-2)"}}

实测 sort.json 内容（根项目「待办」泳道的卡片顺序）：

{"/":{"待办":["写周报"]}}

💡 说明：两个 JSON 的第一层键都是「项目路径」（根项目为 /，子项目为 /子目录名），对应 Tasks.md 的子项目隔离设计；这些文件由应用自动维护，正常情况不需要手工编辑，损坏时可删除后由应用重建（排序/标签颜色会丢失，任务文件不受影响）。

5.6 主题与颜色变量

custom.css 第一行导入主题，三套内置主题实测前若干行对比：

/* adwaita.css（默认） */
:root {
  --color-accent: #1A5FB4;
  --color-foreground: #ffffff;
  --color-background-1: #1c1c1c;
  ...
}
/* nord.css */
:root {
  --color-accent: #5e81ac;
  --color-foreground: #eceff4;
  --color-background-1: #2e3440;
  ...
}
/* catppuccin.css */
:root {
  --color-accent: #1e66f5;
  --color-foreground: #c6d0f5;
  --color-background-1: #303446;
  ...
}

切换主题（即时生效，无需重启）：

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

实测回显：

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

在导入主题后追加变量覆盖即可做品牌色定制，例如把强调色改为红色：

@import url(./color-themes/adwaita.css);
:root {
  --color-accent: #e01b24;
}

官方定义的全部颜色变量及用途：

变量用途
color-accent强调色（按钮、链接高亮）
color-foreground前景文字色
color-background-1主背景
color-background-2第二层背景（编辑器代码块、弹窗、泳道、头部）
color-background-3第三层背景（卡片）
color-background-4第四层背景（按钮、输入框）
color-alt-1 ~ color-alt-7标签配色池；alt-1 兼输入错误与过期日期，alt-3 兼当天到期日期

💡 技术拓展：看板工具的换肤机制主要有两类——

机制特点代表
CSS 变量覆盖改一个入口文件即可全站换肤，无需构建Tasks.md
编译期主题构建时生成主题包，切换粒度更细但需重新构建Ant Design 系

Tasks.md 用 CSS 变量 + 单入口 custom.css，运维侧改文件即生效，无构建链。

六、生产配置模板

适用场景：16 GB 内存以内的团队服务器/NAS，systemd 托管，根路径部署，关闭图片自动清理（团队习惯手工管理附件），文件归属普通用户（UID 1000）：

[Unit]
Description=Tasks.md Kanban Board
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/tasks-md/backend
Environment="PORT=8080"
Environment="CONFIG_DIR=/opt/tasks-md-data/config"
Environment="TASKS_DIR=/opt/tasks-md-data/tasks"
Environment="TITLE=团队任务看板"
Environment="BASE_PATH=/"
Environment="LOCAL_IMAGES_CLEANUP_INTERVAL=0"
Environment="PUID=1000"
Environment="PGID=1000"
ExecStart=/usr/bin/node server.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

应用模板后验证：

systemctl daemon-reload
systemctl restart tasks-md
systemctl is-active tasks-md
curl -s http://localhost:8080/_api/title

实测回显：

active
Tasks.md 生产看板

（模板中 TITLE 不同，返回对应标题。）

⚠️ 安全提示：Tasks.md 3.3.0 无内置认证，生产环境务必配合防火墙（ufw allow from <内网网段> to any port 8080）或带前置认证的反向代理使用。

七、常见问题

Q1：改了环境变量不生效？ 环境变量只在进程启动时读取。确认执行了 systemctl daemon-reload && systemctl restart tasks-md（仅 restart 不重读单元文件）。

Q2：custom.css 改了但页面没变？ 样式文件无需重启，但浏览器有缓存：强制刷新（Ctrl+F5）即可。服务端侧可用 curl -s http://localhost:8080/stylesheets/custom.css 确认返回的是新内容。

Q3：tags.json/sort.json 手工改坏了怎么办？ 停止服务后删除对应文件，重启后应用会在下次写入时重建；任务 Markdown 文件不受任何影响。

Q4：图片上传后过几天消失了？ 是 LOCAL_IMAGES_CLEANUP_INTERVAL 的自动清理：正文里没有以 _api/image/<文件名> 形式引用的图片会被周期删除。将正文图片语法修正为 ![描述](_api/image/<文件名>)，或把该参数置 0。

Q5：BASE_PATH 设置后 PWA 安装按钮消失？ 官方已知限制：BASE_PATH 非 / 时 PWA 不可用，属预期行为。

Q6：泳道/卡片名能用中文吗？ 界面操作完全支持中文。直接调 API 时 URL 路径段必须 percent-encode，否则会出现「创建成功但目录名乱码」等问题，详见本专栏《Tasks.md API 使用详解》篇排障实录。

八、参考链接