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

痛点开场
任务管理这个赛道不缺软件,缺的是「敢把数据放进去」的:
- 云服务说停就停:Wunderlist 死了、Todoist 高级功能年年涨价、TickTick 的数据导出永远差一口气。任务记录是有时间维度的东西,三年后的回顾价值全押在别人服务器上
- 备忘录不是任务管理:iPhone 备忘录能记事,但没有截止日期、没有重复任务、没有「这件事拆成 5 个子任务」的概念,事项一多就是一堆没有结构的流水
- Jira/飞书项目太重:为家里三五个人用的工作流,上企业级工具属于杀鸡用牛刀,光权限配置就能劝退
- Todoist/Trello 官方都有迁移器:Vikunja 内置从 Todoist、Trello、Microsoft To Do 迁移的向导,数据不是从零开始
Vikunja 的定位是「The task manager you actually own」——API + 前端打成一个二进制,一个容器跑完,数据全在你自己的数据库文件里。

能力边界
能干什么(以下全部来自 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
另外想好两个值:
- 对外访问的完整 URL(比如
https://todo.xlee.chat/)。这不是可选项——原因见下一节 - 一串随机 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 版本收录差异很大),没有就走「容器 → 编排」:
- 容器 → 编排 → 创建编排,名字填
vikunja,把上面的 compose 贴进去 - 创建前先在宿主机建好目录:
/opt/vikunja/{files,db}并chown -R 1000:1000。Docker 会以 root 创建缺失的 bind mount 目录,之后权限绕不过来(1Panel 编排的工作目录在/opt/1panel/apps/vikunja/vikunja/,compose 里用相对路径./files就落在那底下) - 端口冲突检查:3456 在 1Panel 机器上一般没人占,冲突就把宿主侧改成
8456:3456 - 起来后
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 那几个环境变量就是最小可用配置了,多一个都不用加。上手路径:
- 建一个项目(比如「家事」),往里加任务
- 任务详情里可以设:截止日期、优先级、标签、子任务、重复规则(每天/每周/工作日)
- 项目页顶部切 List / Gantt / Table / Kanban 四种视图,看板列可以自己加
- 手机浏览器打开同一域名,添加到主屏幕就是 PWA,体验接近原生 App

(图为官网首页的看板视图截图:列 = 待办/进行中/完成,卡片带截止日期、优先级、标签、负责人头像,右侧可直接建新任务。)
提醒与通知配置
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://.../ 并重启容器。
踩坑清单
- 容器秒退,日志只有一句
service.publicurl is required when cors.enable is true——本文头号坑。CORS 默认开 + publicurl 为空 = Fatal。要么设VIKUNJA_SERVICE_PUBLICURL,要么VIKUNJA_CORS_ENABLE=false 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」- rootless Docker 下权限全对还是报 permission denied——用户命名空间重映射把容器内 UID 1000 映射到了宿主另一个 UID。官方给的解法很反直觉:compose 里写
user: "0:0"让容器内以 root 跑(rootless 模式下容器 root 本来就映射成宿主的普通用户,没有风险)。拿不准就docker exec vikunja /app/vikunja/vikunja doctor,它能检测出这个问题 - 重启后所有人被踢下线——
VIKUNJA_SERVICE_SECRET没设,每次启动随机生成。固定下来 docker exec vikunja sh报 executable file not found——scratch 镜像没有 shell,管理命令直接 exec 二进制本体- 提醒时间差 8 小时——
VIKUNJA_SERVICE_TIMEZONE没设,默认 GMT - 在 config.yml 里改
database.path不生效——镜像预设的环境变量VIKUNJA_DATABASE_PATH优先级高于配置文件。要挪数据库位置只能改环境变量或改挂载点 - 照抄网上老教程的
vikunja/api双容器架构——那是 0.x 时代的老结构(API 和前端分两个镜像),现在一个容器搞定。看到vikunja/frontend这个镜像名就知道那篇教程过时了 - 升级跨大版本(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);只想在手机上记两笔的(备忘录就行,别为这个起容器)。
项目地址
- GitHub:https://github.com/go-vikunja/vikunja(AGPL-3.0,当前 v2.7.0)
- 官网与文档:https://vikunja.io/docs/
- 镜像:
vikunja/vikunja:2.7(Docker Hub)或ghcr.io/go-vikunja/vikunja:2.7