Docker搭建Vikunja待办与项目看板

日常安排文章更新、视频制作或服务器维护时，任务往往分散在聊天记录、备忘录和表格里。事情一多，就容易忘记截止日期，也不方便查看哪些工作正在进行。

Vikunja 是一款支持自托管的任务管理工具，可以部署在自己的服务器上，通过浏览器创建待办事项、整理项目，并使用看板查看任务进度。

本教程从安装 Docker 开始，完成 Vikunja 部署、域名 HTTPS、账户创建，以及任务管理和数据备份。

1. 项目介绍

Vikunja 可以把相关任务集中到项目中，支持列表、看板、表格和甘特图等视图，也提供标签、优先级、到期日期、附件以及项目分享功能。

对于个人使用，可以用它管理：

博客选题与文章更新。
视频录制、剪辑和发布。
服务器维护与定期检查。
学习计划和日常待办事项。

本次教程以“博客内容排期”为例，完成创建任务、设置日期、看板流转和附件上传。

部署采用 Vikunja + SQLite + Caddy。SQLite 用于保存任务数据，Caddy 负责域名访问和 HTTPS，适合个人及少量用户使用。

2. 相关地址

项目官网：https://vikunja.io
GitHub 项目：https://github.com/go-vikunja/vikunja
官方部署文档：Docker Compose 部署说明
版本更新说明：Vikunja 更新记录

本文使用 Vikunja 2.8.0 固定版本编写配置，避免后续直接使用浮动标签导致教程界面和部署行为变化。该版本于 2026年11月5日发布。

3. 搭建环境

本次建议准备以下环境：

CPU： 建议 2 核及以上。
内存： 建议 2GB 及以上。
磁盘： 建议至少准备 20GB 可用空间，附件较多时适当增加。
系统： 全新 Debian 12 或 Ubuntu 24.04。
Docker： Docker Engine。
Compose： 使用 docker compose 命令的 Compose 插件。
域名： 准备一个可以管理 DNS 解析的域名。
公网端口： TCP 80、443，同时保留实际使用的 SSH 端口。
应用内部端口： 3456，由 Caddy 转发访问。

以上资源配置是本教程的建议，并非项目官方最低配置。

本次教程推荐使用莱卡云 Linux 云服务器进行搭建。为了方便操作，建议使用没有部署其他网站的新服务器，确保 80 和 443 端口没有被占用。

查看官网购买链接： https://www.lcayun.com

9折优惠码：bloglcayun

开始前，在域名服务商处添加一条 A 记录：

设置项	示例
主机记录	`todo`
记录类型	`A`
记录值	服务器实际公网 IPv4
最终域名	`todo.example.com`

todo.example.com 是示例域名，后面需要替换为自己的实际域名。

首次部署先让域名直接解析到服务器。如果没有配置 IPv6，不要保留指向其他服务器的 AAAA 记录。

同时，在云服务器安全组及已经启用的主机防火墙中允许 TCP 80、443 访问。

4. 搭建视频

本节视频将演示 Docker 安装、项目部署、HTTPS 访问、任务看板使用及数据备份。

视频教程链接：【待补充 B 站或其他发布平台链接】

5. 正式搭建

下面的命令均在服务器终端执行。

使用普通用户连接服务器时，先切换到 root：

sudo -i

5.1 安装 Docker 和 Compose

本站已有服务器上安装 Docker 和 Docker Compose 教程。本篇也保留完整安装步骤，直接按照下面操作即可。

以下命令适用于全新 Debian 或 Ubuntu 系统，使用 Docker 官方软件仓库安装 Engine 和 Compose 插件。

bash <<'DOCKER'
set -e

. /etc/os-release
case "$ID" in
  debian|ubuntu) ;;
  *) echo '本段仅适用于 Debian 或 Ubuntu'; exit 1 ;;
esac

apt-get update
apt-get install -y ca-certificates curl openssl nano

install -m 0755 -d /etc/apt/keyrings
curl -fsSL "https://download.docker.com/linux/$ID/gpg" \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

cat > /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/$ID
Suites: ${UBUNTU_CODENAME:-$VERSION_CODENAME}
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

systemctl enable --now docker

docker --version
docker compose version
docker run --rm hello-world
DOCKER

看到 Docker、Compose 的版本信息，并且 hello-world 输出成功提示后，再继续部署。

如果服务器已经安装 Docker，可以跳过安装部分，先确认：

docker --version
docker compose version

同时确保后续需要的工具已经安装：

apt-get update
apt-get install -y openssl nano

5.2 创建项目目录

创建项目目录，以及数据库、附件和 Caddy 的数据目录：

mkdir -p /opt/vikunja
cd /opt/vikunja

install -d -o 1000 -g 1000 -m 0755 db files
mkdir -p caddy/data caddy/config

官方容器默认使用 UID 1000 运行，因此这里提前设置数据库和附件目录的属主，避免启动或上传文件时出现权限错误。

然后创建环境变量文件。

先把下面的 todo.example.com 换成自己的域名，只填写域名，不要添加 https://。

(
umask 077
cat > .env <<EOF
DOMAIN=todo.example.com
VIKUNJA_SECRET=$(openssl rand -hex 32)
EOF
)

这一步会生成应用密钥并保存到 .env。

仅在首次部署时创建这个文件。已有项目应保留原来的密钥，不要重复覆盖。

项目中的主要目录用途如下：

路径	用途
`/opt/vikunja/.env`	域名和应用密钥
`/opt/vikunja/db`	SQLite 数据库
`/opt/vikunja/files`	上传的附件
`/opt/vikunja/caddy/data`	HTTPS 证书等数据
`/opt/vikunja/caddy/config`	Caddy 配置数据

5.3 创建 Compose 配置

在项目目录执行：

cat > compose.yaml <<'EOF'
services:
  vikunja:
    image: vikunja/vikunja:2.8.0
    restart: unless-stopped
    environment:
      VIKUNJA_SERVICE_PUBLICURL: "https://${DOMAIN}/"
      VIKUNJA_SERVICE_SECRET: "${VIKUNJA_SECRET}"
      VIKUNJA_DATABASE_TYPE: sqlite
      VIKUNJA_DATABASE_PATH: /db/vikunja.db
      VIKUNJA_SERVICE_TIMEZONE: Asia/Shanghai
      VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"
      VIKUNJA_MAILER_ENABLED: "false"
    volumes:
      - ./db:/db
      - ./files:/app/vikunja/files
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  caddy:
    image: caddy:2.11.9-alpine
    restart: unless-stopped
    depends_on:
      - vikunja
    environment:
      DOMAIN: "${DOMAIN}"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy/data:/data
      - ./caddy/config:/config
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
EOF

其中：

VIKUNJA_SERVICE_PUBLICURL 是浏览器实际访问的完整地址。
VIKUNJA_DATABASE_PATH 把数据库固定保存在挂载目录中。
VIKUNJA_SERVICE_SECRET 使用刚才生成的密钥。
本文按个人使用配置，后面通过一条命令创建自己的账户。
邮件服务保持关闭，本次部署不需要自建邮局或配置 SMTP。

SQLite 和附件分别持久化到 db、files，更换容器时继续使用这些目录。

5.4 配置域名 HTTPS

创建 Caddy 配置文件：

cat > Caddyfile <<'EOF'
{$DOMAIN} {
    reverse_proxy vikunja:3456
}
EOF

这里的 {$DOMAIN} 保持原样，实际域名由前面的配置传入。

域名解析正确、验证端口可达时，Caddy 会自动申请 HTTPS 证书并处理续期，同时把 HTTP 访问跳转到 HTTPS。

5.5 启动项目

先检查 Compose 配置：

cd /opt/vikunja
docker compose config -q

没有输出且正常返回，表示配置校验通过。然后拉取镜像并启动：

docker compose pull
docker compose up -d

查看运行状态：

docker compose ps

查看最近的日志：

docker compose logs --tail=50 vikunja caddy

首次启动需要等待应用和证书初始化。两个容器正常运行后，还需要通过浏览器检查 HTTPS 登录页面，确认服务真正可用。

6. 创建账户并登录

在项目目录执行下面的命令。

blogdemo 是示例用户名，可以自行修改；you@example.com 要替换为自己的邮箱地址。

docker compose exec vikunja /app/vikunja/vikunja user create \
  --username blogdemo \
  --email you@example.com

根据终端提示输入并确认密码。密码输入时不显示字符是正常现象，请使用独立的高强度密码并保存好。

官方命令支持交互输入密码，无需把密码写在命令参数里。

接着在自己的电脑浏览器中访问：

https://todo.example.com

将示例域名替换为实际域名，使用刚才创建的用户名和密码登录。

如果界面不是中文，可以在用户设置的语言选项中选择简体中文。

登录后能进入工作区，并正常创建项目，就可以开始使用。

本文没有启用邮件发送，因此不需要接收验证邮件，但也不能使用邮件提醒或邮箱找回密码。忘记密码时，可以使用第9节中的服务器命令重置。

7. 创建待办与项目看板

7.1 创建一个项目

在界面中找到创建项目的入口，新建：

博客内容排期

项目说明可以填写：

用于管理文章选题、教程编写、视频录制和内容发布。

一个项目用于整理一组相关任务。以后也可以分别创建“服务器维护”“学习计划”等项目。

7.2 添加任务并设置日期

在项目中依次添加四项任务：

确定选题
编写教程
录制演示
剪辑发布

打开“编写教程”，补充任务信息：

说明： 完成环境准备、部署命令、使用演示和常见问题。
标签： 内容制作。
到期日期： 选择实际计划完成的日期。

保存后刷新页面，确认任务标题、说明和日期仍然存在。

设置到期日期便于查看时间安排。本教程没有配置邮件通知，不会因此自动收到提醒邮件。

7.3 使用看板管理进度

切换到项目的看板视图，根据界面现有分组，创建或调整为以下三列：

待办
进行中
已完成

然后进行一次任务流转：

将“编写教程”拖到“进行中”。
将已经完成的“确定选题”整理到“已完成”。
打开任务，检查任务本身是否已经标记完成。
刷新页面，确认卡片位置保存成功。

看板列名和任务完成状态需要分别检查。 自己创建一列并命名为“已完成”，不一定会自动改变任务的完成勾选状态。

完成这一步后，就能通过看板快速查看各项工作的进度。

7.4 上传和下载任务附件

在自己电脑上准备一个测试文件：

demo-brief.txt

内容可以填写：

项目教程演示文件，无客户资料。

打开“录制演示”任务，在附件位置上传这个文件。

上传完成后，再把附件下载到自己的电脑，并打开检查内容。这样可以同时验证附件上传、保存和下载是否正常。

需要对外交付较大的素材或文件时，可以结合本站的 Cloudreve 私人网盘搭建教程，在任务说明中记录对应的文件链接。

8. 数据备份与版本更新

8.1 备份项目数据

Vikunja 的任务信息保存在数据库中，上传的文件保存在附件目录中。备份需要同时覆盖这两部分。

本教程把配置、数据库、附件和证书数据都放在 /opt/vikunja，因此可以在停止服务后整体打包。

执行下面的备份时，服务会短暂停止，完成后自动重新启动。

bash <<'BACKUP'
set -e
cd /opt/vikunja

install -d -m 0700 /opt/backups
backup_file="/opt/backups/vikunja-$(date +%Y%m%d-%H%M%S).tar.gz"

docker compose stop
trap 'docker compose start' EXIT

umask 077
tar -czf "$backup_file" -C /opt vikunja
tar -tzf "$backup_file" >/dev/null
ls -lh "$backup_file"
BACKUP

备份文件保存在：

/opt/backups/

命令会检查归档是否可以读取，并显示文件大小。

备份中包含账户数据、应用密钥和证书私钥，应私下保存，并另外复制一份到其他设备。服务恢复后，再登录检查任务和附件是否正常。

8.2 恢复到新服务器

在新服务器完成 Docker 安装，确保目标 /opt/vikunja 不存在，再上传备份文件。

把下面的文件名换成实际备份名称：

tar -xzf /opt/backups/vikunja-实际备份时间.tar.gz -C /opt
cd /opt/vikunja
docker compose up -d

如果迁移后公网 IP 发生变化，需要把域名解析更新到新服务器，并停止旧实例。

恢复后检查：

原账户能否登录。
项目与任务是否完整。
任务日期和看板位置是否正确。
附件能否下载。

已有数据的服务器不要直接覆盖目录。正式长期使用前，建议在测试服务器上完成一次恢复演练。

8.3 更新 Vikunja

本文使用固定镜像版本，更新时先备份，再查看官方更新记录。

编辑配置：

cd /opt/vikunja
nano compose.yaml

将：

image: vikunja/vikunja:2.8.0

改为准备升级的正式版本标签。保存后执行：

docker compose pull
docker compose up -d
docker compose ps

随后重新检查登录、任务编辑和附件下载。

使用固定标签时，只执行 docker compose pull 不会自动切换到另一个版本。 如果升级涉及数据库变更，也不要仅靠换回旧镜像进行回滚，应使用升级前的备份恢复。

9. 常见问题

9.1 域名打不开或证书申请失败

优先检查：

A 记录是否指向当前服务器。
是否存在错误的 AAAA 记录。
安全组和主机防火墙是否允许 TCP 80、443。
80、443 是否被其他网站或面板占用。
.env 中的域名是否填写正确。

查看 Caddy 日志：

cd /opt/vikunja
docker compose logs --tail=100 caddy

9.2 出现 permission denied

检查数据目录权限：

cd /opt/vikunja
ls -ld db files

按照本文创建的目录应归 UID 1000 使用。

如果属主不正确，可修正本项目的数据目录：

chown -R 1000:1000 /opt/vikunja/db /opt/vikunja/files
docker compose restart vikunja

9.3 页面能打开，但登录或接口请求异常

检查 .env 中的域名，以及 Compose 中的 VIKUNJA_SERVICE_PUBLICURL。

浏览器访问的协议、域名和端口应与公开地址一致。本文统一使用：

https://自己的实际域名/

修改 .env 或 Compose 后执行：

cd /opt/vikunja
docker compose up -d

9.4 没有配置邮箱，忘记密码怎么办

先查看用户列表：

cd /opt/vikunja
docker compose exec vikunja /app/vikunja/vikunja user list

找到需要重置的用户 ID，再执行：

docker compose exec vikunja /app/vikunja/vikunja \
  user reset-password 用户ID --direct

把 用户ID 换成实际数字，按照提示输入新密码。

该命令可以直接重置密码，不需要发送找回邮件。

9.5 更新或重启后看不到原来的任务

先检查是否仍在 /opt/vikunja 使用原来的 Compose 配置，以及 db、files 是否正确挂载。

不要为了重新进入系统而删除数据库目录。

如果只是看不到已完成任务，也检查当前视图是否筛选掉了已完成内容。

10. 结尾

完成以上步骤后，就可以通过自己的域名使用 Vikunja，把待办事项、截止日期、任务说明和附件集中管理。

对于内容创作者，可以把选题、写稿、录屏和发布整理成固定流程；对于服务器管理，也可以用它记录维护计划和需要跟进的问题。

平时收集参考资料，可以结合本站的 linkding 私人书签库教程；需要交付文件时，可以使用 Cloudreve 私人网盘。