运维与排障

常用运维命令

命令	说明
`npm run docker:up`	构建并启动应用（连接外部库）
`npm run docker:down`	停止应用容器
`npm run docker:logs`	查看应用容器日志
`npm run build`	生产构建（输出 `.output/`）
`npm run preview`	本地预览构建产物（`nuxt preview`）
`npx drizzle-kit migrate`	本地开发手动执行迁移
`node scripts/generate-init-sql.mjs`	生成初始化 SQL（按需）

备份

数据库：PostgreSQL 用 pg_dump 定期备份，并把备份复制到数据库主机之外的位置。
bash
```
docker exec nexus-postgres pg_dump -U postgres nexus > nexus-$(date +%F).sql
```
上传文件：App Only 模式使用 nexus-uploads 卷并挂载到 /data/uploads。迁移服务器时要与数据库备份一起迁移。

升级流程

git pull 获取新版本。
docker compose up -d --build。
应用启动自动执行迁移、创建/提权管理员、执行模块迁移。
查看日志确认无错误。

常见问题排查

端口冲突（3000 被占用）

宿主机 3000 被占用：停止占用进程，或修改 docker-compose*.yml 的端口映射（如 "3001:3000"），并同步 NUXT_APP_URL 端口。
数据库端口冲突时，先确认连接的是外部数据库还是本机容器，并同步检查 NUXT_DATABASE_URL。不要为解决冲突而直接修改生产数据库端口。

数据库连接失败

检查 NUXT_DATABASE_URL 是否可达。Docker 容器内连宿主机本地库需用 host.docker.internal（Linux 加 --add-host）；连远程库写公网/内网地址。
App Only 模式对 NUXT_DATABASE_URL 等做了 ${VAR:?} 硬校验，缺失会直接报错并提示缺失项。

签到/充值等资产接口返回 403「非法来源」

原因：请求 Origin 的 host 与 NUXT_APP_URL 不一致。
解决：NUXT_APP_URL 必须与浏览器实际访问地址（协议+host+端口）完全一致。服务器 IP 直连用 http://<IP>:3000，域名反代用 https://<domain>。

支付相关接口返回 502

对应支付渠道的商户密钥（微信/支付宝）未配置。未配置时优雅降级返回 502，不影响其他功能。
解决：在 .env 填入对应商户密钥后重建容器。技术接入见技术指南·积分与支付，后台操作见配置支付与充值，更多排查见常见问题·支付。

默认管理员无法登录

确认 NUXT_ADMIN_EMAIL / NUXT_ADMIN_PASSWORD 与登录所用一致。
首次启动会自动创建；若该邮箱已是普通用户，会被自动提权为 admin。
环境变量只参与首次创建管理员。数据库中已有管理员后，修改 NUXT_ADMIN_PASSWORD 并重建不会重置密码。
已配置 SMTP 时优先使用登录页的“忘记密码”。无法使用邮件恢复时，应由有权限的技术人员按正式恢复流程处理数据库，操作前先备份。

OAuth/OIDC 功能提示 JWT 密钥缺失

NUXT_JWT_PRIVATE_KEY / NUXT_JWT_PUBLIC_KEY 用于 OAuth/OIDC 的 RS256 签名，生产缺失时会告警，相关能力不可用。
解决：用 openssl 生成 RSA 密钥对并填入 .env（见环境变量）。

多语言 SEO 异常（hreflang / sitemap 域名不对）

同「403 非法来源」根因：NUXT_APP_URL 域名不正确。修正后重新构建。

日志观察重点

启动期应看到「数据库迁移完成」「默认管理员已创建/已存在」类日志。
邮件未配置 SMTP 时，开发环境会把邮件内容打到日志，可作为本地验证闭环的依据。