Yuvomi 自托管部署教程

本教程基于实际部署记录整理，适用于 CentOS 7 / Linux 服务器环境。

一、环境要求

验证环境命令：

docker --version
docker compose version

二、克隆仓库

git clone https://github.com/ulsklyc/yuvomi.git /opt/yuvomi
cd /opt/yuvomi

若服务器无法直连 GitHub，可在本地克隆后通过 scp 上传到服务器。

三、配置环境变量

3.1 从示例文件复制

cp .env.example .env

3.2 生成安全密钥

执行以下命令生成两个随机密钥：

# 生成 SESSION_SECRET
openssl rand -hex 32

# 生成 DB_ENCRYPTION_KEY
openssl rand -hex 32

3.3 编辑 .env 文件

vi .env

必填项（最小化配置）：

# 服务端口
PORT=3000
NODE_ENV=production
OIKOS_HTTP_PORT=3000

# 会话密钥（替换为上一步生成的值）
SESSION_SECRET=<你的随机密钥1>

# 数据库加密密钥（替换为上一步生成的值）
DB_ENCRYPTION_KEY=<你的随机密钥2>

# 数据库路径（容器内路径，一般不用改）
DB_PATH=/data/oikos.db

# 时区
TZ=Asia/Shanghai

可选项（按需配置）：

# 天气组件（Open-Meteo，免费无需 API Key）
WEATHER_LAT=31.23
WEATHER_LON=121.47
WEATHER_CITY=上海
WEATHER_UNITS=metric

# 速率限制
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_ATTEMPTS=5
RATE_LIMIT_BLOCK_DURATION_MS=900000

# 自动备份
BACKUP_ENABLED=true
BACKUP_SCHEDULE=0 2 * * *
BACKUP_KEEP=7

⚠️ 安全提醒：SESSION_SECRET 和 DB_ENCRYPTION_KEY 是核心密钥，丢失将导致会话失效和数据库无法解密。务必备份 .env 文件。

四、创建数据目录

mkdir -p /opt/yuvomi/data /opt/yuvomi/backups

五、启动服务

5.1 拉取镜像并启动

cd /opt/yuvomi
docker compose pull
docker compose up -d

镜像来源：ghcr.io/ulsklyc/yuvomi:latest（约 484MB）
国内服务器拉取 ghcr.io 可能较慢，耐心等待即可。若网络不稳定出现重试，Docker 会自动重试。

5.2 验证启动状态

# 查看容器状态
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

# 预期输出：
# oikos   Up X seconds (healthy)   0.0.0.0:3000->3000/tcp

# 健康检查
curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/health
# 预期输出：200

# 查看启动日志
docker logs oikos --tail=20

正常启动日志示例：

{"level":"info","mod":"DB","msg":"Connected: /data/oikos.db | Schema v60"}
{"level":"info","mod":"Yuvomi","msg":"Server running on port 3000 | Version 0.75.2"}
{"level":"info","mod":"Yuvomi","msg":"Environment: production"}

六、访问应用

浏览器打开：

http://<服务器IP>:3000

首次访问会进入初始化向导，创建管理员账号即可开始使用。

七、防火墙配置（可选）

如需限制访问来源：

firewalld（CentOS 7 默认）

# 仅允许特定网段访问 3000 端口
firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.26.0.0/16" port port="3000" protocol="tcp" accept'
firewall-cmd --permanent --remove-port=3000/tcp
firewall-cmd --reload

iptables

iptables -A INPUT -p tcp --dport 3000 -s 10.26.0.0/16 -j ACCEPT
iptables -A INPUT -p tcp --dport 3000 -j DROP

八、常用运维命令

cd /opt/yuvomi

# 查看实时日志
docker logs -f oikos

# 重启服务
docker compose restart

# 停止服务
docker compose down

# 更新到最新版本
git pull
docker compose pull
docker compose up -d

# 手动备份数据库
docker exec oikos node -e "require('./server/backup').createBackup()"

# 进入容器排查问题
docker exec -it oikos sh

九、数据持久化说明

迁移服务器时，只需备份 /opt/yuvomi/data 目录和 .env 文件，在新服务器上 docker compose up -d 即可恢复。

十、反向代理配置（可选 HTTPS）

如需通过域名 + HTTPS 访问，推荐使用 Nginx 反向代理：

server {
    listen 443 ssl http2;
    server_name yuvomi.example.com;

    ssl_certificate     /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }
}

启用反向代理后，在 .env 中添加：

SESSION_SECURE=true
TRUST_PROXY=1

然后重启容器：

docker compose restart

故障排查

1. 镜像拉取超时/失败

# 检查网络连通性
curl -I https://ghcr.io

# 重试拉取
docker compose pull

2. 容器启动后立即退出

# 查看退出日志
docker logs oikos

# 常见原因：
# - .env 中 SESSION_SECRET 或 DB_ENCRYPTION_KEY 未设置（仍为占位符）
# - 端口 3000 被占用：netstat -tlnp | grep 3000

3. 数据库迁移失败

# 查看完整启动日志
docker logs oikos 2>&1 | head -50

# 如需重置数据库（⚠️ 会清除所有数据）
rm -f /opt/yuvomi/data/oikos.db
docker compose restart

no such column: r.pushed_at" class="reference-link">4. PushScheduler 报错 no such column: r.pushed_at

此为上游已知问题，不影响核心功能（任务、日历、预算等模块均正常）。推送通知功能可能受限，等待上游修复后 git pull && docker compose pull && docker compose up -d 更新即可。