Vikunja极简教程

Vikunja 极简教程

环境：版本 v2.6.0，docker部署

一、Vikunja 是什么

名字怎么读 ：Vikunja 读作 /vɪˈkuːnjə/，谐音近似「维-库 -尼亚」，重音在中间的「库」。名字取自西班牙语 vicuña （英 $vɪˈkjuːnə$ / 西 $biˈkuɲa$ ）------安第斯山脉的一种珍稀骆驼科动物「小羊驼 / 骆马」，是羊驼的野生近亲；vicuña 一词又源自克丘亚语 wik'uña 。

一句话：Vikunja 是一个用 Go 写的单二进制自托管任务 / 项目管理工具，可以理解为「开源版 Todoist + Trello」------列表、看板、甘特图、表格四种视图共用一套任务数据，一个进程 + 一个 SQLite 文件就能跑起来。

技术栈 ：后端 Go、前端 Vue，编译成单个二进制，默认 SQLite（可切 MySQL/PostgreSQL）。
协议：AGPLv3，代码全公开，数据完全自持，无功能付费墙。
成熟度 ：开发 8 年余，已迭代至 2.x （本文以实际部署的 v2.6.0 简体中文界面为准），官方 Docker 镜像下载量超 700 万。
中文：原生支持简体中文界面（共 33 种语言）。

能力清单

模块	说明
任务管理	子任务分层、10 种任务关联（阻塞 / 顺序 / 相关等）、多级优先级、进度百分比、开始 / 截止 / 结束日期、重复周期、多受理人
多视图	同一批任务在列表 / 看板 / 甘特图 / 表格间切换（每个项目可配多个视图），无需重复录入
提醒	单任务可设多个提醒，站内通知 + 邮件（邮件需配 SMTP 并在设置里开启）
附件	任务可上传 / 下载文件、图片，描述与评论均支持富文本 / Markdown
协作	项目共享给用户或团队、细粒度权限、富文本评论与 emoji 反应、共享链接（可设密码与有效期）
集成	REST API（+ API 令牌）、CalDAV（与手机日历 / 待办客户端同步）、项目级 Webhook、Atom Feed、导入 / 导出、移动端与桌面端 App

资源占用

规模	CPU	内存	数据库
个人 / ≤5 人	1 核	256--512 MB	SQLite 足够
5--20 人	1--2 核	512 MB--1 GB	SQLite 可用，注意写并发
20 人以上	2 核	1--2 GB	建议迁 PostgreSQL，可加 Redis 缓存

对比：它是目前「任务管理」这一档里最轻的自托管方案之一，1 核 1 G 的小机器即可流畅运行，资源占用远低于 Nextcloud / OpenProject / Plane。

二、核心概念与功能模块

本节以实际部署的 v2.6.0 简体中文界面为准。

数据模型（先理清层级）

复制代码

项目 Project                ← 组织任务的核心单位，可嵌套子项目（树状）
   └── 任务 Task            ← 最小工作单元
横切维度（不隶属某个项目）：
   标签 Label（全局分类） · 团队 Team（一组用户，共享赋权） · 保存的过滤器（存起来的筛选条件，跨项目复用）

对象	界面入口	作用	类比
项目 Project	左侧栏「项目」	组织任务的核心容器，可建子项目形成树，每个项目独立配置视图	项目 / 迭代
任务 Task	项目内	具体要做的事，带描述、三种日期、受理人、标签、附件、关联	待办 / 工单
标签 Label	左侧栏「标签」	全局跨项目分类，点标签即筛出所有带它的任务	标签
团队 Team	左侧栏「团队」	一组用户，把项目共享给整个团队并赋权	用户组
保存的过滤器	左侧栏「保存的过滤器」	把一组筛选条件存成侧栏入口（如内置的「My Open Tasks」）	智能视图

⚠️ 两个易错点 ：① v2.x 已取消 旧版的「命名空间 / Namespace」，顶层直接就是项目；② 界面里的「列表」是一种视图类型 （见下），不是装任务的容器，别和旧版的 List 概念混淆。此外系统内置一个默认项目「收件箱 / Inbox」用于临时收集。

四种视图（每个项目可配多个，顶部标签切换，共用同一批任务）

视图	适用场景
列表 List	日常待办，按优先级 / 截止排序，最常用
看板 Kanban	敏捷流转，自定义若干列（bucket，如待办 / 进行中 / 已完成）后拖拽卡片
甘特图 Gantt	中长期排期，时间线展示开始 / 结束 / 进度与依赖连线
表格 Table	批量筛选、编辑、导出任务的多属性明细

⚠️ 没有日历视图 。想按日期看任务，用左侧「即将开始 / Upcoming」页（按日期范围分组的任务列表，非日历）或甘特图。

任务详情能做什么

打开一个任务是一个功能完整的详情页：

分组	能力
主体	标题、富文本 / Markdown 描述、附件（上传 / 下载 / 复制 URL）、富文本评论、emoji 反应
人与状态	受理人（可多人）、看板列（状态）、标记完成、收藏、订阅
日期与时间	开始日期 / 截止日期 / 结束日期、提醒（可多个）、重复间隔
属性	优先级、进度百分比、颜色、标签
关联	10 种关联类型：子任务、上级任务、相关任务、重复、封禁（blocks）、被阻止（blocked by）、优先级（precedes）、关注（follows）、复制自、复制到
其他	移动到其他项目、复制任务、删除

⚠️ 没有工时 / 耗时统计字段（Vikunja 不做 time tracking）。需要工时得靠第三方或 API 自建。

协作与集成

共享项目 ：项目设置菜单 →「共享」，支持三种方式------按用户 、按团队 、生成共享链接（可设权限，外部无需账号）。
CalDAV ：设置 →「CalDAV」页给出接入地址，可用账号密码或专用 CalDAV token 把任务同步到手机系统日历 / 待办 App / Thunderbird 等。
REST API + API 令牌：设置 →「API 令牌」，完整接口可对接脚本、n8n、自动化流程。
Webhook：项目级事件回调（项目设置菜单 →「Webhook」）。
导入 / 导出：设置 →「导出 Vikunja 数据」「从其他服务导入」。
其他：Atom Feed、两步验证（TOTP）、明 / 暗主题、键盘快捷键、Quick Add Magic（添加任务时用前缀快速设日期 / 受理人 / 优先级）。

三、Docker 部署（CentOS 7.6）

1. 前置确认

bash 复制代码

docker version                          # Server 端能连上
docker-compose version                  # 本文统一使用 docker-compose
df -h /var/lib/docker                   # 预留 ≥ 5G（Vikunja 很省）
getenforce                              # 记下结果，Enforcing 时挂载要加 :Z
openssl rand -hex 32                    # 生成 JWTSECRET，复制备用

docker-compose 可能是 v1（Python 版）或 v2（Go 版），本文命令两者通用。compose 文件刻意不写 version: / name: 顶层字段以兼容 v1，项目名默认取目录名 /opt/vikunja → vikunja。

2. 准备目录

bash 复制代码

mkdir -p /opt/vikunja && cd /opt/vikunja
mkdir -p files db backup
chown -R 1000:1000 files db            # 不能省，原因见下

目录	用途
`files`	挂载到容器 `/app/vikunja/files`：任务附件
`db`	挂载到容器 `/db`：SQLite 数据库文件
`backup`	存放备份包

⚠️ chown 这步必须做。 mkdir 建出的目录属主是 root:root，而容器内 Vikunja 以 UID/GID 1000 运行，对 root 属主目录没有写权限。漏了这步，启动后会报数据库无法写入或附件上传失败。

3. 写入 `docker-compose.yml`

bash 复制代码

cat > /opt/vikunja/docker-compose.yml <<'EOF'
services:
  vikunja:
    image: vikunja/vikunja:latest          # 想锁版本可改成具体 tag，如 vikunja/vikunja:2.6
    container_name: vikunja
    environment:
      - VIKUNJA_SERVICE_JWTSECRET=把上一步 openssl 生成的随机串粘到这里
      - VIKUNJA_SERVICE_PUBLICURL=http://task.example.com:3456/   # 改成你的域名或 IP，结尾带 /
      - VIKUNJA_SERVICE_ENABLEREGISTRATION=true                   # 建好账号后改 false 重启
    ports:
      - "3456:3456"
    volumes:
      - ./files:/app/vikunja/files:Z       # :Z 见下方说明
      - ./db:/db:Z
      - /etc/localtime:/etc/localtime:ro   # 保证容器与宿主时区一致（提醒 / 截止时间才准）
    restart: unless-stopped
EOF

部署前必须改的两个值

变量	说明
`VIKUNJA_SERVICE_JWTSECRET`	登录令牌的签名密钥，必须改成强随机串（`openssl rand -hex 32`）。用默认值或弱值有安全风险；上线后再改会导致所有已登录会话失效
`VIKUNJA_SERVICE_PUBLICURL`	必须与浏览器访问地址完全一致（含端口、含结尾斜杠）。写错会导致邮件链接、分享链接、CalDAV 地址全部指向错误位置
两个容易踩的点

:Z（大写）是 SELinux 私有标签。CentOS 7 默认 enforcing，不加会导致容器对挂载目录 permission denied。若 getenforce 返回 Disabled 可去掉。
VIKUNJA_SERVICE_ENABLEREGISTRATION 先保持 true，等第 6 步建好账号后再改 false 并 docker-compose up -d 重启，避免实例对内网外开放注册。

4. 启动

bash 复制代码

cd /opt/vikunja
docker-compose pull
docker-compose up -d
docker-compose ps                    # STATUS 应为 Up
docker-compose logs -f vikunja

日志里看到监听 3456 端口、无报错即成功，Ctrl+C 退出日志跟踪。

5. 放行防火墙端口

bash 复制代码

firewall-cmd --permanent --add-port=3456/tcp
firewall-cmd --reload

Docker 发布端口时通常已直接写 iptables 放行，这步主要让规则显式化、便于审计。

⚠️ CentOS 7 上 systemctl restart firewalld 会清掉 Docker 写的 iptables 规则导致容器断网，重启 firewalld 后请一并 systemctl restart docker。

6. 首次建号并关闭注册

浏览器打开 http://<服务器IP>:3456
首次进入是注册 / 登录页，注册你的第一个账号（即日常管理员）。
登录后回到服务器，把 compose 里的 VIKUNJA_SERVICE_ENABLEREGISTRATION 改为 false：

bash 复制代码

cd /opt/vikunja
sed -i 's/ENABLEREGISTRATION=true/ENABLEREGISTRATION=false/' docker-compose.yml
docker-compose up -d                 # 重新创建容器使配置生效

之后新增成员，由已有账号在「共享」里把项目共享给对方，或临时重开注册让其自助建号后再关闭；普通账号默认看不到实例级管理入口。

四、使用最佳实践

下面均对应 v2.6.0 的实际界面。

1. 结构划分：项目 / 子项目

顶层直接用项目划分（v2.x 没有命名空间）：按「产品线 / 迭代 / 模块 / 专项」建项目，大项目用子项目拆成树，避免单层项目爆炸。
临时想到、还没归类的任务先丢进默认的「收件箱」，定期清空归位。
一条原则：项目是「容器」，标签是「维度」。别为每个负责人 / 每种优先级各建项目，那是标签和「受理人 / 优先级」字段该干的事。

2. 视图选用（每个项目可配多个，顶部标签切换）

你在做什么	用哪个视图
日常推进、看要做什么	列表（按截止 / 优先级排序）
团队站会、看流转卡在哪	看板（自定义待办 / 进行中 / 待验收 / 已完成等列后拖拽）
排期、看里程碑与依赖	甘特图（依赖画成连线）
周期盘点、批量改字段 / 导出	表格

没有日历视图；想「按日期看近期任务」用左侧「即将开始」页（可选日期范围、是否显示无日期 / 过期任务）。

3. 标签 + 优先级 + 保存的过滤器

标签是全局的 （跨项目），做横切分类，如 需求、设计、bug、对接；点任一标签即筛出所有带它的任务。
优先级用任务自带的「设置优先级」字段，别用标签重复表达优先级。
把常用筛选（如「我负责的、本周到期、未完成」）存成「保存的过滤器」，它会出现在左侧栏一键直达，替代反复手点筛选。

4. 任务拆解与依赖（用「相关任务」的关联类型）

拆层级用 子任务 / 上级任务 ；子任务拆到 ≤ 半天 ~ 1 天 粒度，太大就继续拆或升格为独立任务。
表达依赖用 封禁（blocks）/ 被阻止（blocked by） 管前后置，用 优先级（precedes）/ 关注（follows） 管先后顺序，甘特图里会画成连线。
弱关联用 相关任务 ；重复出现的同类任务用 重复 / 复制自 关联溯源。

5. 日期、提醒与重复

任务有 开始 / 截止 / 结束 三个日期，配合 进度百分比 表达完成度，甘特图按这些日期排布。
重要截止设多个提醒 ；要收到邮件提醒，需在「设置 → 通用设置」打开「通过邮件发送任务提醒」，且服务端配好 SMTP（VIKUNJA_MAILER_*，键名以官方文档为准），否则只有站内通知。
例会、周报、巡检类事务用「设置重复间隔」（按天 / 周 / 月 / 年或自定义），别每次手动建。
顺手开启「每天发送未完成摘要」「逾期提醒邮件」，让系统主动催办。

6. 团队协作

共享项目走「项目设置菜单 → 共享」，按用户 / 按团队 / 共享链接 组合使用；遵循最小权限：只读给干系人，读写给执行者。
外部临时协作（如甲方看进度）用共享链接，不必开账号。
任务一律指派受理人 ，「谁在做」一目了然；讨论沉淀在富文本评论 ，轻量反馈用 emoji 反应，别散落在聊天工具。

7. 移动端与集成

手机装 Vikunja App，或用 CalDAV（设置 → CalDAV → 生成专用 token）把任务同步进系统日历 / 待办，随手记、到期提醒。
加任务用 Quick Add Magic 前缀，一行文本直接带出截止日 / 受理人 / 优先级（Vikunja 或 Todoist 风格，在通用设置里选）。
自动化（表单转任务、状态变更通知外部）走 REST API + API 令牌 或项目级 Webhook ；订阅用 Atom Feed。

8. 每周审查（让系统不沦为垃圾场）

概览页扫一遍「当前任务」，即将开始页看近期到期。
看板：清空「进行中」里实际已停滞的卡片。
列表 / 表格：处理过期任务（改期 / 完成 / 拆解），批量改用表格视图。
标签：合并语义重复的；保存的过滤器：删掉不再用的。

五、运维（备份 / 升级 / 安全 / 进阶）

备份与恢复

数据只有两处：db/vikunja.db（SQLite）+ files/（附件）。冷备最稳妥：

bash 复制代码

cd /opt/vikunja
docker-compose stop vikunja
cp db/vikunja.db backup/vikunja-$(date +%F).db
tar czf backup/files-$(date +%F).tar.gz files
docker-compose start vikunja

恢复：停容器 → 用备份覆盖 db/vikunja.db 并解开 files → 起容器。

也可用「设置 → 导出 Vikunja 数据」在网页端导出，或容器内自带的 vikunja dump / vikunja restore 命令打包（含库与附件，参数以官方文档为准）。建议把上面的冷备脚本挂 cron 每日执行。

升级

bash 复制代码

cd /opt/vikunja
docker-compose pull
docker-compose up -d
docker-compose logs -f vikunja       # 确认迁移无报错

升级前先备份。Vikunja 会在启动时自动做数据库迁移。

安全清单

及时升级 ：早期版本（如 0.24.x）披露过若干安全漏洞（XSS、密码重置令牌重用、CalDAV 2FA 绕过等），新版均已修复；务必跑较新版本（本文 v2.6.0），并给账号开两步验证（设置 → 两步验证）。
JWTSECRET 用强随机串，且不要随意变更（变更会踢掉所有登录会话）。
对外网暴露时，前面挂 nginx 反向代理 + HTTPS ，PUBLICURL 相应改成 https://...。
建号后关闭公开注册（见 3.6）。

进阶（按需）

Redis 缓存 ：高负载时加 VIKUNJA_CACHE_ENABLED=true + Redis 容器，降低数据库压力。
切 PostgreSQL：团队变大、写并发高时，从 SQLite 迁 PG（需新建实例后迁移数据，不支持原地切换，别等数据量很大才想起换）。
时区 / 语言 ：已挂载 /etc/localtime 保证时区；界面语言在「设置 → 通用设置 → 本地化」里切简体中文。

六、常见问题排查

现象	原因	处理
容器反复重启 / 起不来	`JWTSECRET` 未设或为空；`db` 目录无写权限	补上随机 `JWTSECRET`；`chown -R 1000:1000 /opt/vikunja/db` 后 `docker-compose up -d`
页面能开，但上传附件失败	`files` 目录属主是 root，或 SELinux 拦截	`chown -R 1000:1000 /opt/vikunja/files`；确认挂载带 `:Z`，必要时 `chcon -Rt container_file_t files`
邮件 / 分享链接 / CalDAV 地址不对	`PUBLICURL` 与实际访问地址不一致	改成浏览器地址栏里真实的协议 + 域名 + 端口 + 结尾 `/`，重启
登录后报令牌错误 / 频繁掉线	`JWTSECRET` 被改动，旧令牌失效	固定一个强随机串不再变更，让用户重新登录
提醒 / 截止时间差几小时	容器时区与宿主不一致	确认挂载了 `/etc/localtime:/etc/localtime:ro`
多人同时操作偶发卡顿 / 锁	SQLite 单写者模型，写并发排队	小团队可忽略；规模上来迁 PostgreSQL
收不到邮件提醒	未配 SMTP，或未开邮件提醒开关	服务端配好 `VIKUNJA_MAILER_*`，并在「设置 → 通用设置」打开「通过邮件发送任务提醒」

Vikunja极简教程

Vikunja 极简教程

一、Vikunja 是什么

能力清单

资源占用

二、核心概念与功能模块

数据模型（先理清层级）

四种视图（每个项目可配多个，顶部标签切换，共用同一批任务）

任务详情能做什么

协作与集成

三、Docker 部署（CentOS 7.6）

1. 前置确认

2. 准备目录

3. 写入 docker-compose.yml

4. 启动

5. 放行防火墙端口

6. 首次建号并关闭注册

四、使用最佳实践

1. 结构划分：项目 / 子项目

2. 视图选用（每个项目可配多个，顶部标签切换）

3. 标签 + 优先级 + 保存的过滤器

4. 任务拆解与依赖（用「相关任务」的关联类型）

5. 日期、提醒与重复

6. 团队协作

7. 移动端与集成

8. 每周审查（让系统不沦为垃圾场）

五、运维（备份 / 升级 / 安全 / 进阶）

备份与恢复

升级

安全清单

进阶（按需）

六、常见问题排查

3. 写入 `docker-compose.yml`