Ubuntu 22.04 安装 Vikunja 2.7.1 指南

Vikunja 是一款开源（AGPL-3.0）的自托管待办与项目管理应用，采用 Go 编写的 API 后端加内嵌 Vue 前端的单二进制架构，默认监听 3456 端口，支持 SQLite / MySQL / MariaDB / PostgreSQL 四种数据库后端。本文在 Ubuntu 22.04 LTS 裸机服务器上从零开始，实测两种官方安装方式：方案 A（官方预编译二进制 + PostgreSQL，推荐生产使用）与方案 B（官方 APT 仓库 deb 包），并完成注册账号、创建项目、创建任务的端到端功能验证。文中所有命令与回显均来自真实服务器实测。

一、环境信息

本次实测的软硬件环境如下：

项目	值
操作系统	Ubuntu 22.04.5 LTS（Jammy Jellyfish）
系统架构	x86_64（amd64）
Vikunja 版本	v2.7.1（2026-10-20 发布，go1.27.3 构建）
数据库	PostgreSQL 14.24（Ubuntu 22.04 官方仓库默认版本）
服务器 IP	192.168.146.131
监听端口	3456（Vikunja 默认）
演示账号	admin / q1w2e3r4

Vikunja 官方对硬件没有硬性要求，实测 2 核 CPU、4GB 内存即可流畅运行；磁盘占用方面，二进制约 64MB，数据量取决于数据库与附件规模。

二、准备工作

Vikunja 以 PostgreSQL 为后端时，数据库需要先于应用就绪。本节完成系统更新与基础依赖安装。

更新软件包索引并安装后续用到的工具：

apt update
apt install -y curl wget unzip gnupg

说明：

unzip 用于解压官方 zip 发行包；
gnupg 用于验证发行包的 GPG 签名；
curl 用于后续 API 验证。

三、安装与配置 PostgreSQL

3.1 安装 PostgreSQL 14

Ubuntu 22.04 官方仓库提供的 PostgreSQL 版本为 14.x，满足 Vikunja 要求的 PostgreSQL 12+：

apt install -y postgresql

安装完成后，PostgreSQL 服务自动启动并加入开机自启。验证服务状态：

systemctl is-active postgresql

回显：

active

查看实际安装的版本：

psql --version

回显：

psql (PostgreSQL) 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1)

3.2 创建数据库与用户

切换到 postgres 系统用户，创建 Vikunja 专用的数据库账号（密码使用演示口令 q1w2e3r4，生产环境请替换为强口令）：

su - postgres -c "psql -c \"CREATE USER vikunja WITH PASSWORD 'q1w2e3r4';\""

回显：

CREATE ROLE

创建数据库并归属该账号：

su - postgres -c "psql -c \"CREATE DATABASE vikunja OWNER vikunja;\""

回显：

CREATE DATABASE

验证数据库已创建：

su - postgres -c "psql -c \"\\l vikunja\""

回显：

                          List of databases
  Name   |  Owner  | Encoding | Collate |  Ctype  | Access privileges
---------+---------+----------+---------+---------+-------------------
 vikunja | vikunja | UTF8     | C.UTF-8 | C.UTF-8 |
(1 row)

四、方案 A：官方二进制安装（推荐）

方案 A 从 Vikunja 官方下载站获取预编译二进制，部署路径清晰、版本可控，适合生产环境。

4.1 下载 Vikunja 2.7.1

官方下载站按版本组织目录，注意版本目录带 v 前缀。下载 zip 包及其 GPG 签名文件：

cd /tmp
wget https://dl.vikunja.io/vikunja/v2.7.1/vikunja-v2.7.1-linux-amd64-full.zip
wget https://dl.vikunja.io/vikunja/v2.7.1/vikunja-v2.7.1-linux-amd64-full.zip.sig

下载完成后核对文件大小（zip 包约 47MB）：

ls -lh /tmp/vikunja-v2.7.1-linux-amd64-full.zip*

回显：

-rw-r--r-- 1 root root 47M Oct 20 21:59 /tmp/vikunja-v2.7.1-linux-amd64-full.zip
-rw-r--r-- 1 root root 565 Oct 20 21:59 /tmp/vikunja-v2.7.1-linux-amd64-full.zip.sig

4.2 GPG 签名验证

Vikunja 官方发行包均使用发布密钥签名，密钥指纹为 7D06 1A4A A614 36B4 0713 D42E FF05 4DAC D908 493A。导入公钥：

gpg --keyserver hkps://keys.openpgp.org --recv-keys FF054DACD908493A

回显（首次导入时）：

gpg: key FF054DACD908493A: "Frederic (Vikunja) (The key to sign vikunja releases.) <frederic@vikunja.io>" not changed
gpg: Total number processed: 1
gpg:              unchanged: 1

执行验签：

gpg --verify vikunja-v2.7.1-linux-amd64-full.zip.sig vikunja-v2.7.1-linux-amd64-full.zip

回显：

gpg: Signature made Tue Oct 20 21:59:14 2026 UTC
gpg:                using RSA key 7D061A4AA61436B40713D42EFF054DACD908493A
gpg: Good signature from "Frederic (Vikunja) (The key to sign vikunja releases.) <frederic@vikunja.io>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7D06 1A4A A614 36B4 0713  D42E FF05 4DAC D908 493A

看到 Good signature 且主密钥指纹与官方公布的一致，即验签通过；末尾的 WARNING 是因为未对该密钥做信任签名，属正常现象。

验签通过后解压，包内共 4 个文件：

unzip -l vikunja-v2.7.1-linux-amd64-full.zip

回显：

Archive:  vikunja-v2.7.1-linux-amd64-full.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
       93  2026-10-20 21:58   vikunja-v2.7.1-linux-amd64.sha256
    39421  2026-10-20 21:58   config.yml.sample
 66233196  2026-10-20 21:58   vikunja-v2.7.1-linux-amd64
    34523  2026-10-20 21:58   LICENSE
---------                     -------
66307233                     4 files

可用包内附带的 sha256 文件二次校验二进制完整性：

unzip -p vikunja-v2.7.1-linux-amd64-full.zip vikunja-v2.7.1-linux-amd64.sha256 > /tmp/vikunja.sha256
unzip -p vikunja-v2.7.1-linux-amd64-full.zip vikunja-v2.7.1-linux-amd64 > /tmp/vikunja-bin
cd /tmp && sed -i 's|vikunja-v2.7.1-linux-amd64$|vikunja-bin|' vikunja.sha256 && sha256sum -c vikunja.sha256

回显：

vikunja-bin: OK

4.3 部署二进制与目录

创建部署目录，将二进制放到 /opt/vikunja/ 并软链到 PATH：

mkdir -p /opt/vikunja/files /opt/vikunja/logs /etc/vikunja
install -m 0755 /tmp/vikunja-bin /opt/vikunja/vikunja
ln -sf /opt/vikunja/vikunja /usr/bin/vikunja

确认版本：

vikunja version

回显：

Vikunja api version v2.7.1
Built with go1.27.3

4.4 编写配置文件

创建 /etc/vikunja/config.yml，写入以下内容：

service:
  publicurl: "http://192.168.146.131:3456/"
  interface: ":3456"
  timezone: "Asia/Shanghai"

database:
  type: "postgres"
  host: "localhost"
  port: 5432
  user: "vikunja"
  password: "q1w2e3r4"
  database: "vikunja"
  sslmode: "disable"

files:
  basepath: "/opt/vikunja/files"

log:
  path: "/opt/vikunja/logs"

关键项说明：

service.publicurl：Vikunja 对外的完整访问地址。v2 版本默认开启 CORS，该值为必填，缺失时服务拒绝启动（报错实录见方案 B 排障一节）；末尾的斜杠不可省略。
database.sslmode：数据库与应用同机部署、走本地回环，设为 disable；跨机部署应开启 TLS 并改为 verify-full。
files.basepath：任务附件存储目录。
log.path：日志目录，systemd 之外的多一份保障。

4.5 创建 systemd 服务

创建 /etc/systemd/system/vikunja.service：

[Unit]
Description=Vikunja
After=network.target postgresql.service
Requires=postgresql.service

[Service]
Type=simple
WorkingDirectory=/opt/vikunja
ExecStart=/usr/bin/vikunja
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

要点：After/Requires 声明对 PostgreSQL 的依赖，保证数据库先于 Vikunja 就绪。

4.6 启动并验证

重载 systemd 并启动服务：

systemctl daemon-reload
systemctl enable vikunja
systemctl start vikunja

查看状态：

systemctl is-active vikunja

回显：

active

首次启动时 Vikunja 会自动执行数据库迁移（建表）。调用 API 信息接口验证：

curl -s http://localhost:3456/api/v1/info | head -c 200

回显（截取）：

{"version":"v2.7.1","frontend_url":"http://192.168.146.131:3456/","motd":"","link_sharing_enabled":true,"max_file_size":"20MB","max_items_per_page":50,"available_migrators":["vikunja-file","ticktick",

返回 version: v2.7.1 即部署成功。浏览器访问 http://192.168.146.131:3456/ 即可看到 Vikunja 登录页。

五、方案 B：官方 APT 仓库安装

方案 B 使用 Vikunja 官方 APT 仓库的 deb 包，安装与后续升级都由 apt 托管，适合希望用包管理器统一维护的场景。注意 deb 包默认使用 SQLite 数据库，适合个人或小团队轻量使用。

5.1 添加 APT 仓库

导入仓库签名密钥并添加源：

wget -qO /usr/share/keyrings/vikunja.asc https://dl.vikunja.io/repos/apt/pubkey.gpg
echo "deb [signed-by=/usr/share/keyrings/vikunja.asc] https://dl.vikunja.io/repos/apt stable main" > /etc/apt/sources.list.d/vikunja.list
apt update

确认仓库已生效：

apt-cache policy vikunja

回显：

vikunja:
  Installed: (none)
  Candidate: 2.7.1
  Version table:
     2.7.1 500
        500 https://dl.vikunja.io/repos/apt stable/main amd64 Packages

5.2 安装 deb 包

apt install -y vikunja

安装完成后确认版本与文件布局：

dpkg -l vikunja | tail -1

回显：

ii  vikunja        2.7.1        amd64        Vikunja is an open-source todo application, written in Go. It lets you create lists,tasks and share them via teams or directly between users.

deb 包的布局与方案 A 不同，实测如下：

路径	用途
/opt/vikunja/vikunja	二进制本体（约 64MB）
/etc/vikunja/config.yml	配置文件
/opt/vikunja/vikunja.db	SQLite 数据库（默认后端，首次启动自动创建）
/usr/lib/systemd/system/vikunja.service	包自带的 systemd 单元

5.3 排障实录：publicurl 缺失导致启动失败

deb 包安装完成后自动 enable 并尝试启动 vikunja.service，但实测首次启动必然失败，查看日志：

journalctl -u vikunja --no-pager | tail -5

回显：

Oct 25 02:00:44 21eb9a4c7462 vikunja[4176]: time=2026-10-25T02:00:44.112Z level=INFO msg="Using config file: /etc/vikunja/config.yml"
Oct 25 02:00:44 21eb9a4c7462 vikunja[4176]: time=2026-10-25T02:00:44.112Z level=ERROR msg="service.publicurl is required when cors.enable is true"
Oct 25 02:00:44 21eb9a4c7462 systemd[1]: vikunja.service: Main process exited, code=exited, status=1/FAILURE
Oct 25 02:00:44 21eb9a4c7462 systemd[1]: vikunja.service: Failed with result 'exit-code'.

原因：v2 版本默认 cors.enable: true，强制要求配置 service.publicurl；而 deb 包自带的 /etc/vikunja/config.yml 共 560 行，第 1~555 行全部是注释掉的配置样例，真正的实际生效块在文件末尾，内容只有安装时自动生成的 secret：

service:
  secret: "olKhSppGHa0BPCAkfNWifuWzEld48C9p"

正确的修复方法是在文件末尾的实际生效块中追加 publicurl（注意不要改动顶部样例区的注释）：

sed -i '/^  secret: "olKh/a\  publicurl: "http://192.168.146.131:3456/"' /etc/vikunja/config.yml

或者直接用编辑器把文件末尾改为：

service:
  secret: "olKhSppGHa0BPCAkfNWifuWzEld48C9p"
  publicurl: "http://192.168.146.131:3456/"

两个不要：一不要把第 1 行的 # service: 解开注释，那样会与文件末尾的 service: 块冲突，启动直接报 YAML 解析错误 yaml: unmarshal errors: line 558: mapping key "service" already defined at line 1；二不要只解开样例区里的 # publicurl: 注释而保持其顶层的 # service: 不动，那样 publicurl 会成为没有父键的孤立行，YAML 静默忽略后依旧报 service.publicurl is required。

清除失败计数并重新启动：

systemctl reset-failed vikunja
systemctl start vikunja

5.4 启动验证

systemctl is-active vikunja

回显：

active

验证 API：

curl -s http://localhost:3456/api/v1/info | head -c 200

回显（截取）：

{"version":"v2.7.1","frontend_url":"http://192.168.146.131:3456/","motd":"","link_sharing_enabled":true,"max_file_size":"20MB","max_items_per_page":50,"available_migrators":["vikunja-file","ticktick",

查看自动创建的 SQLite 数据文件（默认存放在工作目录 /opt/vikunja/ 下）：

ls -lh /opt/vikunja/

回显：

total 67M
drwx------ 3 root root 4.0K Oct 25 02:02 files
-rwxr-xr-x 1 root root  64M Oct 20 22:01 vikunja
-rw------- 1 root root 4.0K Oct 25 02:02 vikunja.db
-rw------- 1 root root  32K Oct 25 02:02 vikunja.db-shm
-rw------- 1 root root 3.0M Oct 25 02:02 vikunja.db-wal

六、功能验证（API 端到端）

无论方案 A 还是方案 B，安装完成后都执行以下端到端验证，确认应用真正可用。以下回显取自方案 B 环境，方案 A 验证过程完全相同。

6.1 注册演示账号

curl -s -X POST http://localhost:3456/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"q1w2e3r4","email":"admin@quzuo.local"}'

回显：

{"id":1,"name":"","username":"admin","created":"2026-10-25T02:02:27Z","updated":"2026-10-25T02:02:27.255478823Z"}

返回用户 id=1 即注册成功。

6.2 登录获取令牌

curl -s -X POST http://localhost:3456/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"q1w2e3r4"}'

回显（截取，实际 token 为 317 字符的 JWT）：

{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3OTI4OTQzNTUsImlhdCI6M...

6.3 创建项目与任务

将上一步的 token 存入变量，创建一个项目（创建项目用 PUT /api/v1/projects）：

TOKEN=<上一步返回的 token>
curl -s -X PUT http://localhost:3456/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"apt 安装验收项目"}'

回显（解析后）：

项目ID: 2 | 标题: apt 安装验收项目

在项目下创建任务：

curl -s -X PUT http://localhost:3456/api/v1/projects/2/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"验证 apt 安装流程"}'

回显（解析后）：

任务ID: 1 | 标题: 验证 apt 安装流程

列出项目任务确认数据落库：

curl -s http://localhost:3456/api/v1/projects/2/tasks \
  -H "Authorization: Bearer $TOKEN"

回显（解析后）：

 - 验证 apt 安装流程

至此，从安装到可用的完整闭环验证通过。浏览器访问 http://192.168.146.131:3456/，使用 admin / q1w2e3r4 登录即可看到上述项目与任务。

七、两种安装方式对比

维度	方案 A：官方二进制	方案 B：APT 仓库
数据库后端	自选（本文用 PostgreSQL）	默认 SQLite，可改配
安装来源	dl.vikunja.io 版本目录	dl.vikunja.io/repos/apt
版本控制	手动下载指定版本，精确可控	apt 托管，跟随 stable 通道
升级方式	下载新版替换二进制	apt upgrade 一键升级
完整性校验	GPG 签名 + sha256	apt 签名机制自动完成
配置初始状态	自行编写，干净直观	560 行样例 + 末尾生效块，需注意 publicurl 必填
适用场景	生产环境、需要外部数据库	个人/小团队、快速部署

生产环境建议选择方案 A + PostgreSQL/MySQL，避免 SQLite 在并发写入下的局限。

八、卸载

方案 A 卸载：

systemctl stop vikunja
systemctl disable vikunja
rm -f /etc/systemd/system/vikunja.service /usr/bin/vikunja
systemctl daemon-reload
rm -rf /opt/vikunja /etc/vikunja

数据库按需保留；确认不再需要时执行：

su - postgres -c "psql -c \"DROP DATABASE vikunja;\""
su - postgres -c "psql -c \"DROP USER vikunja;\""

方案 B 卸载：

systemctl stop vikunja
apt remove --purge vikunja
rm -rf /opt/vikunja /etc/vikunja

--purge 会删除包内配置文件，但 /opt/vikunja/ 下的数据文件（含 SQLite 库）需手动清理。

九、常见问题

Q1：启动报 service.publicurl is required when cors.enable is true？ A：v2 版本默认开启 CORS，必须显式配置 service.publicurl 且末尾带斜杠，值为用户实际访问 Vikunja 的完整 URL。deb 包用户注意改在文件末尾的实际生效块里，详见 5.3 节。

Q2：能不能只用 SQLite 跑生产？ A：官方定位 SQLite 为个人轻量使用。Vikunja 的 SQLite 后端在并发写场景下受限于单写锁，团队使用请选 PostgreSQL（12+）或 MySQL 8.0+ / MariaDB 10.2+。

Q3：如何把端口从 3456 改成 80/443？ A：修改配置中 service.interface 为 :80 或 :443 并同步修改 service.publicurl。生产环境更推荐前置 Nginx/Caddy 反向代理终止 TLS，Vikunja 保持监听 127.0.0.1:3456。

Q4：升级二进制版本怎么做？ A：停服务 → 下载新版 zip 并验签 → 替换 /opt/vikunja/vikunja → 启动服务。Vikunja 启动时会自动执行数据库迁移，无需手工干预；升级前建议用 vikunja dump 备份（CLI 用法见本专栏《Vikunja 2.7.1 常用 CLI 命令详解》）。

十、参考链接

Vikunja 官方文档-安装页：https://vikunja.io/docs/installing/
Vikunja 官方下载站：https://dl.vikunja.io/vikunja/
Vikunja 官方 APT 仓库说明：https://vikunja.io/docs/installing/#debian-ubuntu-packages
Vikunja 源码仓库（GitHub 镜像）：https://github.com/go-vikunja/vikunja
PostgreSQL 14 官方文档：https://www.postgresql.org/docs/14/