这是「Docker 好项目」系列的第 26 期。这个系列写到现在,服务和数据都搬回家了,但有一块一直没碰:任务管理。要干活的事散在微信收藏、备忘录、群消息里,谁催一下才想起来哪件没做。这期介绍 Vikunja——一个把任务清单、看板、甘特图、日历全装进一个容器的自托管任务管理器,AGPL-3.0,Go 写的单二进制,自带前端,SQLite 就能跑。

vikunja 效果图

痛点开场

任务管理这个赛道不缺软件,缺的是「敢把数据放进去」的:

  • 云服务说停就停:Wunderlist 死了、Todoist 高级功能年年涨价、TickTick 的数据导出永远差一口气。任务记录是有时间维度的东西,三年后的回顾价值全押在别人服务器上
  • 备忘录不是任务管理:iPhone 备忘录能记事,但没有截止日期、没有重复任务、没有「这件事拆成 5 个子任务」的概念,事项一多就是一堆没有结构的流水
  • Jira/飞书项目太重:为家里三五个人用的工作流,上企业级工具属于杀鸡用牛刀,光权限配置就能劝退
  • Todoist/Trello 官方都有迁移器:Vikunja 内置从 Todoist、Trello、Microsoft To Do 迁移的向导,数据不是从零开始

Vikunja 的定位是「The task manager you actually own」——API + 前端打成一个二进制,一个容器跑完,数据全在你自己的数据库文件里。

Vikunja 官网截图:首页 Overview,最近打开的项目和当前任务一屏收齐

能力边界

能干什么(以下全部来自 v2.7.0 源码与官方文档核实,不是 README 吹的)

  • 四种任务视图:列表、看板(Kanban)、甘特图、表格,同一个项目随时切换,拖拽改状态
  • 完整的任务模型:子任务、标签、优先级、负责人、截止/开始日期、附件(默认单文件 20MB)、评论、重复任务、任务间关联(被阻塞/相关)
  • 提醒是内置的:每分钟扫一次到期提醒(RegisterReminderCron 源码注释原文),逾期任务每天定时汇总——不需要你外面再挂个 cron
  • CalDAV:默认开启,手机日历 App 直接订阅 https://你的域名/dav/,BasicAuth 认证,任务直接出现在系统日历里
  • 团队与共享:团队、项目分享、链接分享(默认开启),适合家庭/小团队
  • API Token + Webhooks:Web 默认开启,事件列表在 /api/v1/webhooks/events,可以接第 13 期 ntfy 做「任务到期推手机」
  • 登录方式可扩展:本地密码(默认开)、OIDC(可接第 20 期 Pocket ID)、LDAP 全支持,TOTP 两步验证也有
  • 内置数据导出:vikunja dump 一条命令把配置 + 附件 + 数据库打成 zip

不干什么

  • 不做即时通讯。任务评论归任务评论,别拿它替代聊天
  • 不是笔记软件。Markdown 富文本编辑器有,但它是为任务描述服务的,长文档请用 Memos(第 7 期)或专门的 wiki
  • 没有原生的国内推送通道。提醒走邮件(需自配 SMTP)和 webhook,想要微信/钉钉推送得自己用 webhook 桥一下
  • 单机为主。没有官方集群方案,SQLite 单文件在几百个任务下毫无压力,但上万人请老老实实切 PostgreSQL
  • 甘特图没有资源负荷图。它能画时间条,但不会告诉你「这个人这周排满了没有」

部署前准备

项 说明
镜像 vikunja/vikunja(Docker Hub)或 ghcr.io/go-vikunja/vikunja(我实测两边都在,国内拉 Docker Hub 卡住可换 GHCR 或镜像加速)
tag 规则 次版本 tag 真滚动:实测 2.7 == 2.7.0 == latest(digest 全同),历史 2.6==2.6.0、2.5==2.5.0 也一致。tag 不带 v 前缀(v2.7.0 实测 404)。本期推荐 :2.7,不想追 patch 就钉 :2.7.0
平台 amd64 / arm64 / arm(32 位两种变体),树莓派、飞牛 NAS ARM 盒子都能跑
端口 3456(service.interface 默认 :3456,镜像 EXPOSE 3456)
数据卷 两个都要挂:/app/vikunja/files(任务附件、头像、项目背景)+ /db(SQLite 数据库文件,镜像已预设 VIKUNJA_DATABASE_PATH=/db/vikunja.db)
运行用户 UID 1000、无组(镜像 USER 1000,源码 Dockerfile 原样)。挂载目录必须先 chown 1000,否则启动直接 permission denied
基础镜像 FROM scratch——容器里除了那个二进制什么都没有:没有 shell、没有 curl、没有 wget。docker exec vikunja sh 会直接报 exec: "sh": executable file not found,排障全靠 docker logs 和二进制自带的子命令
健康检查 镜像无内置 healthcheck(config blob 实测 Healthcheck = null),但二进制自带 healthcheck 子命令(会 ping 数据库),正好用来补 compose 健康检查,见下文

动手前,宿主机先建目录并授权(1Panel 自建编排也一样,Docker 不会替你把属主改成 1000):

mkdir -p ./files ./db
chown -R 1000:1000 ./files ./db

另外想好两个值:

  1. 对外访问的完整 URL(比如 https://todo.xlee.chat/)。这不是可选项——原因见下一节
  2. 一串随机 secret(openssl rand -base64 32 的输出),后面解释为什么必须手动给

docker run 一行版

docker run -d --name vikunja --restart unless-stopped \
  -p 3456:3456 \
  -e VIKUNJA_SERVICE_PUBLICURL=http://192.168.31.193:3456/ \
  -e VIKUNJA_SERVICE_SECRET=$(openssl rand -base64 32) \
  -e VIKUNJA_SERVICE_TIMEZONE=Asia/Shanghai \
  -v $PWD/files:/app/vikunja/files \
  -v $PWD/db:/db \
  vikunja/vikunja:2.7

注意第一行环境变量不是可省的——不设它容器会立刻退出,日志里一句 service.publicurl is required when cors.enable is true 就没了。这是我给这个项目定的「本系列头号坑」:

Vikunja 的 CORS 默认是开着的(cors.enable 默认 true),而源码里有一条硬校验:CORS 开着且 service.publicurl 为空,直接 log.Fatalf 退出。(pkg/config/config.go 第 795 行,逐字核实过。)所以网上那些「docker run 一行起来」的老教程,现在照抄必挂——这是 2.x 的新行为。

如果你就是想在内网裸 IP 跑、不想设 URL,官方也留了后门:VIKUNJA_CORS_ENABLE=false 关掉 CORS 即可。但只要打算配反代上域名,就老老实实设 VIKUNJA_SERVICE_PUBLICURL。

VIKUNJA_SERVICE_SECRET 同理:不设的话,Vikunja 每次启动会随机生成一个(generateServiceSecretIfEmpty,32 字节随机数)。后果是所有已签发的登录 token 在重启后全部失效——用户全部被踢下线,定时提醒的凭证也作废。生产环境必须自己固定一串。

docker-compose 推荐版

SQLite 单机版(个人/家庭场景的推荐姿势,少一个数据库容器少一份维护):

services:
  vikunja:
    image: vikunja/vikunja:2.7
    container_name: vikunja
    restart: unless-stopped
    ports:
      - "3456:3456"
    environment:
      # 必填:对外完整 URL,带协议,末尾斜杠可加可不加(程序会自动补)
      VIKUNJA_SERVICE_PUBLICURL: https://todo.example.com/
      # 必填:固定 secret,否则每次重启全体掉线。生成:openssl rand -base64 32
      VIKUNJA_SERVICE_SECRET: "把这串换成你自己的随机串"
      # 强烈建议:不设默认 GMT,提醒时间会差 8 小时
      VIKUNJA_SERVICE_TIMEZONE: Asia/Shanghai
      # 注册完自己的账号后改成 false,防止陌生人注册
      VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"
      # 数据库文件路径。镜像已预设 /db/vikunja.db,写出来是为了明确它落在下面哪个卷
      VIKUNJA_DATABASE_PATH: /db/vikunja.db
    volumes:
      - ./files:/app/vikunja/files
      - ./db:/db
    # scratch 镜像没有 curl/wget,用二进制自带的子命令做健康检查
    healthcheck:
      test: ["CMD", "/app/vikunja/vikunja", "healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

人多(几个家庭共享、小团队)建议切 PostgreSQL,官方 compose 的写法:

services:
  vikunja:
    image: vikunja/vikunja:2.7
    environment:
      VIKUNJA_SERVICE_PUBLICURL: https://todo.example.com/
      VIKUNJA_SERVICE_SECRET: "随机串"
      VIKUNJA_SERVICE_TIMEZONE: Asia/Shanghai
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: "数据库密码"
      VIKUNJA_DATABASE_DATABASE: vikunja
    ports:
      - "3456:3456"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: "数据库密码"
    volumes:
      - ./db:/var/lib/postgresql
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U $$POSTGRES_USER"]
      interval: 30s
      start_period: 15s

注意两点:postgres:18 起 VOLUME 从 /var/lib/postgresql/data 改成了 /var/lib/postgresql(第 14 期 Paperless 那期踩过同款);Vikunja 支持的数据库只有 SQLite/MySQL/PostgreSQL 三种,官方明确建议 MySQL 场景用 utf8mb4 字符集,否则中文和 emoji 会写不进去。

配置项逐项解释

变量 推荐值 为什么这么写
VIKUNJA_SERVICE_PUBLICURL https://你的域名/ 必填。CORS 默认开启,缺了它容器起不来。同时也是邮件里回链、前端调 API 的基准地址,写错会出现「能登录但保存任务报错」这类灵异问题
VIKUNJA_SERVICE_SECRET openssl rand -base64 32 的输出 必填。签 JWT 用的。不设的话每次启动随机生成 → 每次重启全员掉线
VIKUNJA_SERVICE_TIMEZONE Asia/Shanghai 默认 GMT。影响提醒触发的时刻解释,「每天 9:00 提醒」不设时区就会在北京时间 17:00 才响
VIKUNJA_SERVICE_ENABLEREGISTRATION 建完号改 "false" 默认 true——任何人打开你的域名都能注册账号。和第 3 期 Vaultwarden 的 SIGNUPS_ALLOWED 一个道理,家庭部署必关
VIKUNJA_DATABASE_PATH /db/vikunja.db 镜像已预设,写出来是提醒你:改数据库位置必须用这个环境变量。在挂载的 config.yml 里写 database.path 不会生效——官方文档原话「environment variables take precedence over the config file」
VIKUNJA_FILES_MAXSIZE 默认 20MB 任务附件单文件上限。要传大文件就加大,同时反代的 client_max_body_size 必须跟着改,否则先在 nginx 那层被 413
VIKUNJA_SERVICE_ENABLETASKATTACHMENTS 默认 true 关掉可以省一个文件目录的维护成本,纯清单用户可以关
VIKUNJA_SERVICE_ENABLECALDAV 默认 true 手机日历订阅任务。用不上可以在环境变量里关掉,少一个 BasicAuth 入口
VIKUNJA_RATELIMIT_ENABLED 公网建议 "true" 默认关。开了之后 ratelimit.limit(默认 100 次/60 秒)+ ratelimit.noauthlimit(未认证 10 次)兜底防爆破
VIKUNJA_KEYVALUE_TYPE 默认 memory 限流计数器的存储。单机 memory 够用;官方文档还演示了接 Redis 提升多实例场景性能,家庭场景没必要
VIKUNJA_SENTRY_ENABLED 默认 false 错误上报到官方 Sentry。默认就是关的,隐私敏感的确认一眼即可
VIKUNJA_LOG_LEVEL 默认 INFO 排障改 DEBUG。日志默认走 stdout(docker logs 看),文件日志默认在容器内 /app/vikunja/logs,没挂载、重建容器就没了——反正 stdout 够用

环境变量命名规律:配置文件里的 service.publicurl 对应 VIKUNJA_SERVICE_PUBLICURL——viper 的 env 前缀 vikunja + 点号换下划线(源码 SetEnvKeyReplacer 那两行)。所有配置项的键名和默认值都在仓库的 config-raw.json 里,比翻文档快。

1Panel 面板怎么搞

按本系列一贯的写法:先在应用商店搜一下当前版本收录情况(不同 1Panel 版本收录差异很大),没有就走「容器 → 编排」:

  1. 容器 → 编排 → 创建编排,名字填 vikunja,把上面的 compose 贴进去
  2. 创建前先在宿主机建好目录:/opt/vikunja/{files,db} 并 chown -R 1000:1000。Docker 会以 root 创建缺失的 bind mount 目录,之后权限绕不过来(1Panel 编排的工作目录在 /opt/1panel/apps/vikunja/vikunja/,compose 里用相对路径 ./files 就落在那底下)
  3. 端口冲突检查:3456 在 1Panel 机器上一般没人占,冲突就把宿主侧改成 8456:3456
  4. 起来后 docker logs -f vikunja 看到监听 3456、没有 Fatal 即成功

排障提示(scratch 镜像专属):docker exec -it vikunja sh 是进不去的,容器里没有 shell。要跑管理命令,直接 exec 那个二进制:

# 诊断:检查文件权限、数据库连通、用户命名空间映射等
docker exec vikunja /app/vikunja/vikunja doctor

# 版本
docker exec vikunja /app/vikunja/vikunja version

doctor 是官方给 scratch 镜像准备的排障入口,rootless Docker 的 UID 映射问题它也能查出来。

首次访问

浏览器打开 http://服务器IP:3456(或你反代的域名),点 Register 注册第一个账号,登进去就是默认项目。注册完立刻把 VIKUNJA_SERVICE_ENABLEREGISTRATION 改成 false 重启,这是公网部署的第一件安全大事。

不想开注册、想用命令行建账号(比如先关注册再补人):

docker exec vikunja /app/vikunja/vikunja user create \
  -u lee -e lee@example.com -p '你的密码'

# 把某个用户提升为管理员(第一个注册的用户默认就是 admin,一般用不到)
docker exec vikunja /app/vikunja/vikunja user set-admin --admin lee

界面语言:右上角头像 → Settings → Language 里选中文,所有文案都是完整翻译过的(Vikunja 用 Crowdin 做社区翻译,中文覆盖很全)。

最小可用配置

上面 compose 那几个环境变量就是最小可用配置了,多一个都不用加。上手路径:

  1. 建一个项目(比如「家事」),往里加任务
  2. 任务详情里可以设:截止日期、优先级、标签、子任务、重复规则(每天/每周/工作日)
  3. 项目页顶部切 List / Gantt / Table / Kanban 四种视图,看板列可以自己加
  4. 手机浏览器打开同一域名,添加到主屏幕就是 PWA,体验接近原生 App

Vikunja 官网截图:项目内四种视图切换,这里正在用看板拖任务

(图为官网首页的看板视图截图:列 = 待办/进行中/完成,卡片带截止日期、优先级、标签、负责人头像,右侧可直接建新任务。)

提醒与通知配置

Vikunja 的提醒不依赖外部 cron——源码里注册了每分钟跑一次的提醒扫描和每日逾期汇总,起容器就生效。要做的只是选「提醒发到哪」:

方式一:邮件(要配 SMTP)

environment:
  VIKUNJA_MAILER_ENABLED: "true"
  VIKUNJA_MAILER_HOST: smtp.example.com
  VIKUNJA_MAILER_PORT: "587"
  VIKUNJA_MAILER_USERNAME: "no-reply@example.com"
  VIKUNJA_MAILER_PASSWORD: "SMTP密码"
  VIKUNJA_MAILER_FROMEMAIL: "no-reply@example.com"

配完先发封测试邮件验证:

docker exec vikunja /app/vikunja/vikunja testmail 你的邮箱@example.com

方式二:Webhook → ntfy(不需要 SMTP,推送更及时)

Vikunja 的 Webhooks 默认开启,在「设置 → Webhooks」里添加一个目标 URL、勾选事件(如 task.reminder.fired)。配合第 13 期的 ntfy:

URL:  https://ntfy.example.com/任务提醒主题

ntfy 那边不用做任何配置,收到 POST 就能推到手机。想确认有哪些事件可勾,接口直接给:

curl http://127.0.0.1:3456/api/v1/webhooks/events

方式三:Atom 订阅

通知流还能以 Atom 输出:https://你的域名/feeds/notifications.atom(BasicAuth 认证),丢给第 12 期 Miniflux 当一条普通源,提醒就汇进了你的 RSS 阅读器。

反向代理与 HTTPS

Vikunja 就一个普通 HTTP 服务,反代没有特殊要求,没有 WebSocket 强依赖(NPM 里勾不勾 Websockets 都能用,勾上更好)。

1Panel / 手写 nginx 的最小配置:

server {
    listen 443 ssl;
    server_name todo.example.com;
    # ssl_certificate / ssl_certificate_key 略

    location / {
        proxy_pass http://127.0.0.1:3456;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 20M;   # 与 VIKUNJA_FILES_MAXSIZE 保持一致
    }
}

两个细节:

  • client_max_body_size 必须不小于 Vikunja 的附件上限(默认 20MB),否则传大附件时 nginx 先报 413,你会误以为是 Vikunja 的问题。官方文档也是这么提醒的
  • 反代后客户端真实 IP 会变成反代的 IP,如果想用限流按真实用户计数,补一个 VIKUNJA_SERVICE_TRUSTEDPROXIES=127.0.0.1/32(或你反代的网段)

第 2 期 Nginx Proxy Manager 用户:Proxy Host → Forward 到 服务器IP:3456,Scheme 选 http,SSL 页签申请 Let's Encrypt 证书并开 Force SSL 即可,Advanced 里什么都不用填。

配完 HTTPS 后,VIKUNJA_SERVICE_PUBLICURL 记得同步改成 https://.../ 并重启容器。

踩坑清单

  1. 容器秒退,日志只有一句 service.publicurl is required when cors.enable is true——本文头号坑。CORS 默认开 + publicurl 为空 = Fatal。要么设 VIKUNJA_SERVICE_PUBLICURL,要么 VIKUNJA_CORS_ENABLE=false
  2. permission denied 起不来——宿主机目录没 chown 1000。镜像以 UID 1000 运行且没有 root 降权逻辑,不会自己改属主。官方文档原话:「Vikunja will not try to acquire ownership of the files folder, as that would mean it had to run as root」
  3. rootless Docker 下权限全对还是报 permission denied——用户命名空间重映射把容器内 UID 1000 映射到了宿主另一个 UID。官方给的解法很反直觉:compose 里写 user: "0:0" 让容器内以 root 跑(rootless 模式下容器 root 本来就映射成宿主的普通用户,没有风险)。拿不准就 docker exec vikunja /app/vikunja/vikunja doctor,它能检测出这个问题
  4. 重启后所有人被踢下线——VIKUNJA_SERVICE_SECRET 没设,每次启动随机生成。固定下来
  5. docker exec vikunja sh 报 executable file not found——scratch 镜像没有 shell,管理命令直接 exec 二进制本体
  6. 提醒时间差 8 小时——VIKUNJA_SERVICE_TIMEZONE 没设,默认 GMT
  7. 在 config.yml 里改 database.path 不生效——镜像预设的环境变量 VIKUNJA_DATABASE_PATH 优先级高于配置文件。要挪数据库位置只能改环境变量或改挂载点
  8. 照抄网上老教程的 vikunja/api 双容器架构——那是 0.x 时代的老结构(API 和前端分两个镜像),现在一个容器搞定。看到 vikunja/frontend 这个镜像名就知道那篇教程过时了
  9. 升级跨大版本(0.x → 1.x/2.x)前先备份——官方 changelog 里 1.0/2.0 都有 breaking changes(权限模型重命名、配置键废弃等),跨版本前先 vikunja dump 一份

备份

Vikunja 自带一条命令全量备份,产物是包含配置 + 附件 + 数据库的 zip:

docker exec vikunja /app/vikunja/vikunja dump -p /db -f vikunja-backup.zip
# 产物落在容器内 /db/vikunja-backup.zip,也就是宿主机 ./db/vikunja-backup.zip

-p /db 是故意写到已经挂载出来的目录里,省得再 docker cp。恢复:

docker exec vikunja /app/vikunja/vikunja restore /db/vikunja-backup.zip
# 只想恢复数据不想覆盖配置时加 --preserve-config

懒人方案(SQLite 场景可用,但有 WAL 一致性风险,官方推荐还是 dump):

# 停容器后直接打包两个目录
docker stop vikunja && tar czf vikunja-$(date +%F).tar.gz files db && docker start vikunja

把备份目录喂给第 21 期 Kopia 或第 23 期 Syncthing 异地同步,这条链路这个系列已经铺好了。

小结

适合谁:想要一个数据完全自主、界面不难看、功能够用不臃肿的任务管理器的个人/家庭/小团队;已经用着 Todoist/Trello 想搬家的;想把任务提醒接进自己推送链路(ntfy/邮件/RSS)的折腾党。一个容器 + 两个挂载目录的运维成本,在这个系列里属于最轻的一档。

不适合谁:需要多人实时协作编辑同一个文档的(那是飞书/Notion 的活);需要甘特图资源负荷、工时统计这类重项目管理功能的(去看 OpenProject/Focalboard);只想在手机上记两笔的(备忘录就行,别为这个起容器)。

项目地址