常见问题
先区分问题发生在哪一步：程序启动、账号登录、模型调用，还是结果展示。请求失败时保留发生时间和请求 ID，方便在后台定位。
登录后又回到登录页
检查访问协议与 OBSIDIAN_COOKIE_SECURE 是否一致。非开发模式下默认启用 Secure Cookie，普通 HTTP 部署可能无法保存或发送登录 Cookie。
本机 HTTP 测试可设 OBSIDIAN_COOKIE_SECURE=false 后重启。对外部署应使用 HTTPS 并保持该值为 true。
不知道管理员账号
系统没有默认账号。没有通过初始化环境变量创建账号时，首个注册用户成为管理员。
OBSIDIAN_ADMIN_USER 和 OBSIDIAN_ADMIN_PASSWORD 只用于空用户表的初始化。已有账号后修改这两个变量，不会修改账号密码。
程序无法启动
| 现象 | 检查内容 |
|---|---|
| 端口被占用 | 调整 OBSIDIAN_ADDR，容器同时检查宿主机端口映射 |
| PostgreSQL 连接失败 | 驱动、DSN、数据库是否就绪，以及网络与认证配置 |
| 数据目录无法写入 | 目录或数据卷权限，程序使用的运行用户 |
| 实例密钥长度错误 | OBSIDIAN_SECRET_KEY 至少需要 16 个字符 |
| 数据库迁移失败 | 保留启动日志与备份，核对当前程序版本及数据库状态 |
不要通过删除数据库或实例密钥来尝试修复启动问题。密钥改变后，原来加密的服务商凭据可能无法解密。
页面空白或缺少前端资源
从源码构建时，先运行 npm --prefix web ci 和 npm --prefix web run build，再执行 Go 构建。前端产物位于 internal/web/dist，会在编译时嵌入程序。
模型列表为空
依次检查：
- 服务商与模型是否已启用。
- 用户组是否允许该模型，或已开启全部模型访问。
- 模型是否因可用性策略被自动停用。
- API Key 是否绑定了其他模型。
管理员与普通用户的权限不同。需要排查普通用户的问题时，按该用户的分组和密钥检查。
网页能对话，API 却不能调用
/v1 接口需要 API Key，不能复用登录 Cookie。还需开启全站 API，以及普通用户组的 API 权限。
全站关闭时，/v1 返回 404 api_disabled。无效密钥、账号不可用或用户组没有 API 权限等情况可返回 401 invalid_api_key；这是网关有意统一的错误，不能只凭它判断密钥拼写错误。
先用同一把密钥请求 /v1/models，再复制返回的模型 ID 调用。详见接入与鉴权。
上游连接失败
在服务商配置中核对协议、Base URL 和 API Key，再检查服务端访问上游的网络。Base URL 不应包含完整的聊天请求路径。
OBSIDIAN_UPSTREAM_DIAL_TIMEOUT 限制建立连接的时间，OBSIDIAN_UPSTREAM_HEADER_TIMEOUT 限制等待响应头的时间；它们都不是整段回答的时限。
回答一次性出现或中途断开
一次性出现通常需要检查反向代理缓冲。Nginx 使用 proxy_buffering off；其他代理也需要允许流式数据及时下发。
中途断开时，检查浏览器网络、代理超时和 OBSIDIAN_UPSTREAM_REQUEST_TIMEOUT。默认总请求超时为 0，表示由请求上下文控制。刷新或关闭网页会取消请求。
还有额度，却提示不足
请求发出前会预留预计用量，结束后再按实际消耗结算。预留金额较高或已有请求在生成时，暂时可用额度可能少于页面里最后一次显示的数值。
同时检查具体超限的周期、RPM、TPM 与并发限制。减少单次输出上限或等待已有请求完成后再试。
历史图片无法显示
上传图片默认不会长期保留：attachments.retain=false 时，发送后会清理图片数据。已启用保留的实例也可能配置了按天或定时清理。
附件二进制保存在数据库中，不存在需要单独检查的 uploads 目录。已经被清理的数据，需要从包含该数据的备份恢复。