# 常见错误与解决 (/docs/reference/common-issues)

## 无法启动服务

### `Error: JWT_SECRET is required`

- **原因**：JWT 签名密钥未设置，这是启动服务的必填项。
- **解决**：在环境变量中添加 `JWT_SECRET`，设置一个随机字符串即可。

### `Error: SNOWFLAKE_WORKER_ID is required`

- **原因**：Snowflake 工作节点 ID 未设置。
- **解决**：在环境变量中添加 `SNOWFLAKE_WORKER_ID=1`（单实例部署填 1 即可）。

### `Connection refused to postgres:5432`

- **原因**：PostgreSQL 服务未启动，或连接配置错误。
- **解决**：
  1. 确认 PostgreSQL 容器或服务已正常运行；
  2. 检查 `PG_HOST`、`PG_PORT`、`PG_USER`、`PG_PASSWORD` 是否正确；
  3. Docker 部署时，注意容器之间的网络是否互通。

## 无法访问后台

### 502 Bad Gateway

- **原因**：反向代理（Nginx/Caddy）配置错误，无法正确代理到后端服务。
- **解决**：检查反向代理配置中的 upstream 地址和端口，确认后端服务端口是否为 `2333`（或你自定义的 `PORT`）。

### 证书错误

- **原因**：HTTPS/SSL 证书配置有问题，或使用了自签名证书但客户端不信任。
- **解决**：检查证书是否过期，确认 Nginx/Caddy 的 SSL 配置正确，必要时重新申请证书。

## 无法访问前端

### 升级 v13 后 error.api_fetchError Not found

- **原因**：代码逻辑要求至少需要有一篇手记（详见 [此 issues 讨论](https://github.com/innei-dev/yohaku/issues/151#issuecomment-4642861551)）
- **解决**：发布一篇手记保证 `api/v3/aggregate` 能正常工作。

## 功能异常

### 搜索不工作

- **原因**：Algolia 配置缺失或错误，索引未建立。
- **解决**：
  1. 进入后台检查 Algolia 的 `IndexName`、`AppID`、`ApiKey` 是否填写正确；
  2. 确认 Algolia 控制台中索引已创建且有数据；
  3. 保存配置后等待片刻，让系统自动同步索引。

### 第三方登录失败

- **原因**：OAuth 应用的回调地址（Callback URL）与后台配置不一致。
- **解决**：
  1. 在 GitHub/Google 控制台核对 `Authorization callback URL`；
  2. 在 Mix Space 后台复制正确的回调地址并填入 OAuth 应用；
  3. 确认 `ALLOWED_ORIGINS` 中包含了你的前端域名。

## 数据相关

### 备份文件无法下载

- **原因**：备份目录权限不足，或备份路径配置错误。
- **解决**：检查备份目录的读写权限，确认运行服务的用户有权访问该目录。

### 回滚后数据丢失

- **原因**：回滚时使用了错误的备份文件，或备份文件本身已损坏。
- **解决**：
  1. 确认使用的是正确的备份文件（注意时间戳）；
  2. 回滚前务必先对当前数据做一次备份；
  3. 若备份文件损坏，尝试使用更早的备份。