最稳省事的方式是docker部署：需提前创建vikunja-files和vikunja-db目录并chown 1000:1000，用docker run -d启动，访问http://localhost:3456；生产环境必须用docker-compose.yml统一管理端口、挂载路径与环境变量，避免sqlite并发问题及配置错误。
docker run 单命令快速验证能否跑起来
适合测试或临时使用，不用写 docker-compose.yml，但必须提前建目录并设对 UID：
- 执行
mkdir -p $PWD/vikunja-files $PWD/vikunja-db—— 两个目录必须存在且为空 - 立刻执行
chown 1000:1000 $PWD/vikunja-files $PWD/vikunja-db—— 容器默认以 UID 1000 运行，挂载目录权限不对会静默退出或报permission denied - 启动命令里
-v的容器内路径必须是/app/vikunja/files和/app/vikunja/db，少一个/app前缀，数据就写到容器内存里，重启即丢 -
VIKUNJA_SERVICE_PUBLICURL必须带协议和端口，比如http://localhost:3456，否则邮件、OAuth、Webhook 全失效
docker-compose.yml 生产环境必备配置
单命令只够尝鲜，正式用必须上 docker-compose.yml，否则环境变量难追踪、重启策略不统一、日志没落盘：
-
ports要写成"3456:3456"，不是"3456"—— 后者只暴露容器端口，宿主机根本连不上 -
VIKUNJA_DATABASE_PATH值必须和volumes挂载到容器内的路径严格一致，比如挂载的是./vikunja-db:/app/vikunja/db，那这里就得填/app/vikunja/db/vikunja.db - SQLite 并发写入会触发
database is locked，多人高频使用时建议换 MySQL/MariaDB；若坚持用 SQLite，确保vikunja-db所在文件系统不是 NFS 或某些云盘（锁机制不兼容）
二进制安装 systemd 服务起不来怎么办
常见报错是 Failed at step EXEC spawning /opt/vikunja/vikunja: Permission denied 或 WorkingDirectory= does not exist：
-
ExecStart=必须写绝对路径，且/opt/vikunja/vikunja文件要有+x权限：chmod +x /opt/vikunja/vikunja -
WorkingDirectory=必须指向含config.yml的目录（如/opt/vikunja），否则它 fallback 到内置默认值，SQLite 可能写错位置 - 别用
root启动；在 service 文件里加User=1000和Group=1000，并确保/opt/vikunja/files和/opt/vikunja/db所属 UID/GID 是 1000
Docker 容器连不上 MySQL/MariaDB
日志里反复出现 failed to connect to database: dial tcp: lookup mariadb on 127.0.0.11:53: no such host 或 access denied for user 'vikunja'@'172.x.x.x'：
-
VIKUNJA_DATABASE_HOST必须填服务名（如mariadb），不能填localhost或127.0.0.1—— Docker 网络里localhost指容器自己 -
depends_on只控制启动顺序，不保证 DB 已 ready；加healthcheck或用wait-for-it.sh更可靠 - MySQL 初始化时，
MYSQL_DATABASE和VIKUNJA_DATABASE_NAME必须一致；同时确认VIKUNJA_DATABASE_USER在 MySQL 里有对应账号，且允许从%或具体网段登录
chown -R 1000:1000 没跑全，或者只改了父目录没覆盖 files/ 和 db/ 子目录。
