Ubuntu 22.04 安装 Tasks.md 3.3.0 指南
在 Ubuntu 22.04 服务器上从源码完整安装 Tasks.md 3.3.0：Node.js 18 环境、源码获取、前端构建、后端部署、systemd 托管与验证，含在线与二进制两套实测方案。
Ubuntu 22.04 安装 Tasks.md 3.3.0 指南
目标：在一台全新的 Ubuntu 22.04 服务器上，从源码完整安装 Tasks.md 3.3.0（Node.js 环境准备 → 源码获取 → 前端构建 → 后端部署 → systemd 托管 → 验证），并给出在线/二进制两套可选方案。本文所有命令与回显均已在 Ubuntu 22.04.5 LTS（x86_64）实测通过。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（Jammy），x86_64
- 组件版本：Tasks.md 3.3.0（GitHub Releases 当前 Latest，发布于 2026-03-08；查询日期 2026-10-25）
- 运行时：Node.js 18.20.8（方案 A，NodeSource 仓库）/ Node.js 18.20.4（方案 B，官方二进制包）；npm 10.8.2
- 源码目录：
/opt/tasks-md（frontend前端、backend后端） - 数据目录：
/opt/tasks-md-data（tasks任务文件、config配置/图片/排序） - 监听端口：8080（HTTP，单进程同时提供页面与
/_api接口） - 托管方式：systemd 单元
tasks-md.service
⚠️ 网络说明（实测时的真实网络情况，2026-10-25）：NodeSource 仓库与 Ubuntu 官方 apt 源直连可用；GitHub 克隆、源码 tar.gz 下载与 npm 依赖安装在实测时直连失败或过慢（
git clone直连报GnuTLS recv error (-54)），已统一改用代理http://192.168.1.62:7897完成，文中对应步骤均已标注。读者网络正常时可去掉代理直接执行。
二、前置条件
开始安装前，确认服务器满足以下条件：
- 一台可 sudo 的 Ubuntu 22.04 服务器（内存 ≥ 1 GB，磁盘 ≥ 2 GB 空闲；实测安装后源码目录占用约 634 MB，含依赖）。
- 能访问外网（或配置好代理）下载 Node.js 与源码。
- 以 root 或具备 sudo 权限的账号执行；本文命令均以 root 直接执行演示。
- systemd 可用（
systemctl is-system-running返回running或degraded均可；degraded只表示个别无关单元未启动，不影响本服务托管）。
更新软件包索引并安装基础工具：
apt-get update
apt-get install -y curl ca-certificates git xz-utils
实测回显（节选）：
Processing triggers for ca-certificates (20260816ubuntu0.22.04.1) ...
Updating certificates in /etc/ssl/certs...
0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.
⚠️ 排障实录：
xz-utils必须装上。实测漏装时解压 Node.js 官方二进制包直接报错：tar (child): xz: Cannot exec: No such file or directory，安装xz-utils后恢复正常。
三、版本选型说明
Tasks.md 的版本节奏与发布产物对应关系：
| 版本 | 发布日期 | 说明 |
|---|---|---|
| 3.3.0 | 2026-03-08 | 当前最新稳定版（Latest），本文安装目标 |
| 3.2.2 | 2025-12-29 | 3.2 系列最后一个补丁版 |
| 3.0.x | 2025-08 ~ 2025-09 | 3.x 首个系列；2.x 升级 3.x 需按官方 migration-guide 处理 |
查询最新版本的命令（Release 页跳转会指向最新 tag）：
curl -sI https://github.com/BaldissaraMatheus/Tasks.md/releases/latest | grep -i '^location:'
本文固定安装 3.3.0，保证步骤与回显可复现。
四、在线安装方案（A：NodeSource 仓库 + git clone）
本方案通过 NodeSource 仓库安装 Node.js 18，再用 git 克隆指定版本源码，适合可联网的服务器，是官方源码运行方式的完整落地。
4.1 安装 Node.js 18（NodeSource 仓库）
Ubuntu 22.04 自带仓库的 Node.js 版本过老（12.x），无法构建本项目（Vite 5 要求 Node ≥ 18），因此使用 NodeSource 官方仓库：
curl -fsSL https://deb.nodesource.com/setup_18.x -o /tmp/nodesource_setup.sh
bash /tmp/nodesource_setup.sh
apt-get install -y nodejs
实测回显（节选）：
2026-10-25 01:00:48 - Repository configured successfully.
2026-10-25 01:00:48 - To install Node.js, run: apt install nodejs -y
...
Unpacking nodejs (18.20.8-1nodesource1) ...
Setting up nodejs (18.20.8-1nodesource1) ...
验证版本：
node --version
npm --version
实测回显：
v18.20.8
10.8.2
4.2 克隆 Tasks.md 3.3.0 源码
git clone --depth 1 --branch 3.3.0 https://github.com/BaldissaraMatheus/Tasks.md.git /opt/tasks-md
⚠️ 实测时 GitHub 直连失败，报错
fatal: unable to access 'https://github.com/BaldissaraMatheus/Tasks.md.git/': GnuTLS recv error (-54): Error in the pull function.，改用代理后成功：export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897 git clone --depth 1 --branch 3.3.0 https://github.com/BaldissaraMatheus/Tasks.md.git /opt/tasks-md
再克隆前端依赖的 Stacks-Editor 子模块（作者 fork 版，frontend/package.json 以 file:src/components/Stacks-Editor 引用，必须存在，否则前端无法构建）：
git clone --depth 1 https://github.com/BaldissaraMatheus/Stacks-Editor /opt/tasks-md/frontend/src/components/Stacks-Editor
ls /opt/tasks-md
实测回显：
Dockerfile
KEYBOARD_SHORTCUTS.md
LICENSE
README.md
backend
entrypoint.sh
frontend
migration-guide.md
public
4.3 安装依赖并构建前端
先装 Stacks-Editor 子模块依赖，再装前端依赖，最后构建生产产物（npm 仓库实测走代理）：
cd /opt/tasks-md/frontend/src/components/Stacks-Editor
npm ci --no-audit
cd /opt/tasks-md/frontend
npm ci --no-audit
npm run build
实测回显（节选）：
mode generateSW
precache 12 entries (16.13 KiB)
files generated
dist/sw.js
dist/workbox-5ffe50d4.js
warnings
assets/index-BxLGbK63.js is 2.24 MB, and won't be precached. Configure maximumFileSizeToCacheInBytes to change this limit.
构建产物 dist/ 内容：
assets
favicon
index.html
manifest.webmanifest
registerSW.js
stylesheets
sw.js
workbox-5ffe50d4.js
💡 说明：末行警告表示主 bundle 2.24 MB 超出 PWA 预缓存默认上限，不影响使用，仅该文件不进入 Service Worker 预缓存。
4.4 安装后端依赖
cd /opt/tasks-md/backend
npm ci --no-audit
实测回显（节选）：
15 packages are looking for funding
run `npm fund` for details
4.5 准备数据目录并部署前端产物
后端从 backend/static/ 提供页面，从 CONFIG_DIR 读取样式/标签/排序配置，从 TASKS_DIR 读写任务 Markdown 文件。按下述结构准备：
mkdir -p /opt/tasks-md-data/tasks
mkdir -p /opt/tasks-md-data/config/stylesheets
mkdir -p /opt/tasks-md-data/config/images
mkdir -p /opt/tasks-md-data/config/sort
mkdir -p /opt/tasks-md/backend/static
cp -r /opt/tasks-md/frontend/dist/. /opt/tasks-md/backend/static/
echo "@import url(./color-themes/adwaita.css);" > /opt/tasks-md-data/config/stylesheets/custom.css
cp -r /opt/tasks-md/backend/static/stylesheets/. /opt/tasks-md-data/config/stylesheets/
ls /opt/tasks-md-data/config/stylesheets/
实测回显：
color-themes
custom.css
各目录作用：
| 路径 | 作用 |
|---|---|
/opt/tasks-md-data/tasks | 任务数据根目录；一级子目录 = 泳道，.md 文件 = 卡片 |
/opt/tasks-md-data/config/stylesheets | 自定义样式 custom.css 与三套内置主题 |
/opt/tasks-md-data/config/images | 卡片中上传的本地图片 |
/opt/tasks-md-data/config/sort | 排序数据目录（同时会生成 config/sort.json） |
五、二进制安装方案（B：Node.js 官方 tar.xz + 源码 tar.gz）
本方案不依赖 apt 第三方仓库与 git，直接下载 Node.js 官方二进制包和 GitHub 发布的源码压缩包，适合无法使用 NodeSource 仓库或需固定二进制校验的场景。
5.1 安装 Node.js 官方二进制包
cd /opt
curl -fsSLO https://nodejs.org/dist/v18.20.4/node-v18.20.4-linux-x64.tar.xz
tar -xf node-v18.20.4-linux-x64.tar.xz
/opt/node-v18.20.4-linux-x64/bin/node -v
实测回显：
-rw-r--r-- 1 root root 23M Oct 25 01:21 node-v18.20.4-linux-x64.tar.xz
v18.20.4
⚠️ 排障实录：若服务器未装
xz-utils，tar -xf会报xz: Cannot exec: No such file or directory；执行apt-get install -y xz-utils后重试即可。
如需全局使用，可建软链：
ln -sf /opt/node-v18.20.4-linux-x64/bin/node /usr/local/bin/node
ln -sf /opt/node-v18.20.4-linux-x64/bin/npm /usr/local/bin/npm
node -v
5.2 下载并解压源码 tar.gz
cd /opt
curl -fsSLo tasks-md-3.3.0.tar.gz https://codeload.github.com/BaldissaraMatheus/Tasks.md/tar.gz/refs/tags/3.3.0
tar -xzf tasks-md-3.3.0.tar.gz
mv Tasks.md-3.3.0 tasks-md
实测回显：
-rw-r--r-- 1 root root 760K Oct 25 01:21 tasks-md-3.3.0.tar.gz
⚠️ 注意：GitHub 自动生成的源码压缩包不含 git 子模块，因此 Stacks-Editor 目录为空，必须单独下载：
curl -fsSLo stacks-editor.tar.gz https://codeload.github.com/BaldissaraMatheus/Stacks-Editor/tar.gz/refs/heads/main tar -xzf stacks-editor.tar.gz mkdir -p /opt/tasks-md/frontend/src/components/Stacks-Editor cp -r Stacks-Editor-main/. /opt/tasks-md/frontend/src/components/Stacks-Editor/
后续「安装依赖 → 构建前端 → 部署产物 → systemd 托管」与方案 A 的 4.3 ~ 4.5 节及第六章完全相同，不再重复。
六、方案对比与选择建议
| 维度 | 方案 A（NodeSource + git clone） | 方案 B（官方二进制 + 源码 tar.gz） |
|---|---|---|
| Node.js 来源 | NodeSource apt 仓库（18.20.8） | nodejs.org 官方 tar.xz（18.20.4） |
| 源码获取 | git clone（可精确切 tag） | codeload tar.gz（固定 tag） |
| 依赖工具 | git | 仅需 curl + xz-utils |
| 子模块处理 | git clone 后单独 clone Stacks-Editor | 需手工下载 Stacks-Editor 压缩包（tar.gz 不含子模块） |
| 后续升级 | git fetch --tags 切换版本 | 重新下载新版本压缩包 |
| 适用场景 | 可联网、需灵活切换版本 | 无法添加第三方 apt 仓库、需固定二进制 |
选择建议：常规可联网服务器用方案 A 更顺手；对 apt 仓库来源有审计要求或需完全固定二进制的环境用方案 B。
七、systemd 托管与验证
两套方案安装完成后，统一用 systemd 托管后端进程。
7.1 创建专用用户与服务单元
useradd -r -s /usr/sbin/nologin tasksmd
cat > /etc/systemd/system/tasks-md.service <<'EOF'
[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="BASE_PATH=/"
Environment="LOCAL_IMAGES_CLEANUP_INTERVAL=1440"
Environment="TITLE=Tasks.md 生产看板"
ExecStart=/usr/bin/node server.js
Restart=on-failure
[Install]
WantedBy=multi-user.target
EOF
⚠️ 排障实录：
Environment=的值含空格时必须整体加引号（Environment="TITLE=Tasks.md 生产看板"）。实测不加引号写成Environment=TITLE=Tasks.md 生产看板时，systemd 只把Tasks.md传入进程，调用GET /_api/title返回被截断的Tasks.md；加引号重启后返回完整的Tasks.md 生产看板。
逐行说明关键项：
WorkingDirectory=/opt/tasks-md/backend：后端入口server.js所在目录，前端静态文件也由其下的static/提供；PORT：监听端口，默认 8080；CONFIG_DIR/TASKS_DIR：配置与任务数据目录，即 4.5 节准备的路径；BASE_PATH：子路径反代时填写（如/tasks），根路径部署填/；LOCAL_IMAGES_CLEANUP_INTERVAL：未引用图片清理周期（分钟），0 为关闭；ExecStart=/usr/bin/node server.js：方案 A 的 node 在/usr/bin/node；若用方案 B 且未建软链，改为/opt/node-v18.20.4-linux-x64/bin/node。
7.2 启动并设为开机自启
systemctl daemon-reload
systemctl enable tasks-md
systemctl start tasks-md
systemctl is-active tasks-md
实测回显：
Created symlink /etc/systemd/system/multi-user.target.wants/tasks-md.service → /etc/systemd/system/tasks-md.service.
active
查看运行状态：
systemctl status tasks-md --no-pager
实测回显：
● tasks-md.service - Tasks.md Kanban Board
Loaded: loaded (/etc/systemd/system/tasks-md.service; enabled; vendor preset: enabled)
Active: active (running) since Sun 2026-10-25 01:02:54 UTC; 2s ago
Main PID: 3775 (node)
Tasks: 11 (limit: 3612)
Memory: 28.6M
CPU: 153ms
└─3775 /usr/bin/node server.js
7.3 端口与页面验证
ss -ltnp | grep 8080
curl -s http://localhost:8080/_api/title
curl -s -o /dev/null -w "GET / -> %{http_code}\n" http://localhost:8080/
实测回显：
LISTEN 0 511 *:8080 *:* users:(("node",pid=3822,fd=18))
Tasks.md 生产看板
GET / -> 200
⚠️ 排障实录：Ubuntu 22.04 最小化安装可能没有
ss命令（报bash: ss: command not found），执行apt-get install -y iproute2补齐。
至此，浏览器访问 http://<服务器IP>:8080 即可打开 Tasks.md 看板。进程常驻内存约 28.6 MB，非常轻量。
八、配置说明
Tasks.md 运行期全部通过环境变量配置（无配置文件），常用项：
| 环境变量 | 默认值 | 说明 |
|---|---|---|
PORT | 8080 | HTTP 监听端口 |
CONFIG_DIR | config（相对后端目录） | 配置目录（样式/标签/排序/图片） |
TASKS_DIR | tasks（相对后端目录） | 任务数据目录 |
TITLE | 空 | 页面顶部与浏览器标签页标题 |
BASE_PATH | 空 | 子路径反代的基础路径；注意置非 / 时 PWA 不可用 |
LOCAL_IMAGES_CLEANUP_INTERVAL | 1440（分钟） | 未被引用图片的清理周期，0 关闭 |
PUID / PGID | 0 | 新建文件/目录的属主 UID/GID（后端会对新建资源 chown） |
修改方式：编辑 /etc/systemd/system/tasks-md.service 中的 Environment= 行，然后：
systemctl daemon-reload
systemctl restart tasks-md
更完整的参数含义与配置文件（custom.css、tags.json、sort.json）说明见本专栏《Tasks.md 配置参数详解》篇。
九、常见问题
Q1：git clone 报 GnuTLS recv error (-54)？
实测 GitHub 直连被干扰时的典型报错。改用代理：export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897 后重试；或使用方案 B 的源码压缩包（同样走代理）。
Q2：npm ci 报 ENOENT ... package-lock.json？
Stacks-Editor 子模块没有安装，或进入的目录不对。确认 frontend/src/components/Stacks-Editor 已按 4.2 节克隆（方案 B 按 5.2 节手工补齐）。
Q3：npm run build 报内存不足？
1 GB 内存的服务器实测可以完成构建；若仍失败，可加 swap 或设 NODE_OPTIONS=--max-old-space-size=768 后重试。
Q4：启动后访问 8080 空白或 404？
依次检查：systemctl status tasks-md 是否 active；/opt/tasks-md/backend/static/ 下是否有 index.html（4.5 节拷贝是否执行）；journalctl -u tasks-md --no-pager 查看报错。
Q5：页面标题显示不全（只有「Tasks.md」）？
systemd 单元里 Environment=TITLE=... 含空格未加引号导致截断，按 7.1 节 ⚠️ 修正后 systemctl daemon-reload && systemctl restart tasks-md。
Q6：中文泳道/卡片通过 API 操作异常？ URL 中的中文路径必须 percent-encode 后再请求，详见本专栏《Tasks.md API 使用详解》篇的排障实录。
十、卸载与清理
按以下顺序卸载（每步单独执行）：
systemctl stop tasks-md
systemctl disable tasks-md
rm /etc/systemd/system/tasks-md.service
systemctl daemon-reload
实测回显：
Removed /etc/systemd/system/multi-user.target.wants/tasks-md.service.
删除程序与数据目录（会删除全部任务 Markdown 文件，先备份再执行）：
rm -rf /opt/tasks-md /opt/tasks-md-data
userdel tasksmd 2>/dev/null
方案 A 如需连 Node.js 一并卸载：apt-get remove -y nodejs && rm /etc/apt/sources.list.d/nodesource.list；方案 B 卸载 Node.js：rm -rf /opt/node-v18.20.4-linux-x64 /usr/local/bin/node /usr/local/bin/npm。
十一、参考链接
- Tasks.md GitHub 仓库：https://github.com/BaldissaraMatheus/Tasks.md
- Tasks.md 3.3.0 Release：https://github.com/BaldissaraMatheus/Tasks.md/releases/tag/3.3.0
- 2.x → 3.x 迁移说明：https://github.com/BaldissaraMatheus/Tasks.md/blob/main/migration-guide.md
- NodeSource Node.js 仓库：https://github.com/nodesource/distributions
- Node.js 官方下载：https://nodejs.org/dist/