Skip to content

FAQ

Jump to bottom
李源炳 edited this page Jun 19, 2026 · 1 revision

常见问题（FAQ）

部署相关

Q: Docker Compose 启动后后端健康检查失败，报 connection refused？

A: 大多数情况是 PostgreSQL 还未完全就绪。等待 10–30 秒后 imboy 容器会自动重试。查看状态：

docker compose logs postgres | tail -20
docker compose logs imboy | grep -E "ready|error"

Q: Caddy 无法申请 SSL 证书？

A: 确认域名 DNS 已指向当前服务器，且服务器 80 端口可从外网访问（Let's Encrypt 需要验证域名所有权）。Caddy 日志：

docker compose logs caddy | grep -i tls

Q: preflight.sh 报端口被占用？

A: 找出占用进程并终止：

sudo lsof -i :80
sudo lsof -i :443
sudo kill -9 <PID>

Q: 数据库迁移失败，提示 extension "timescaledb" not found？

A: 使用官方镜像 ghcr.io/imboy-pub/postgres:18，该镜像预装了 TimescaleDB、pgcrypto 和 pg_jieba。不要使用官方 postgres 镜像替换。

性能相关

Q: 在线用户超过 500 后服务变慢？

A: 检查 PostgreSQL 连接池配置（IMBOY_DB_POOL），建议设为 CPU 核数 × 2。也可水平扩展后端节点（见 Kubernetes 部署）。

Q: WebSocket 连接数上限是多少？

A: 默认无硬性上限，受系统文件描述符数量约束。建议设置：

# /etc/sysctl.conf
fs.file-max = 1000000
net.core.somaxconn = 65535

单节点经测试可稳定支持 10,000+ 并发 WebSocket 连接（8 核 16GB 服务器）。

功能相关

Q: E2EE 开启后，历史消息还能看到吗？

A: 开启 E2EE 之前发送的消息（明文存储）仍然可读。之后的新消息将以密文存储，只有持有私钥的设备可解密。

Q: 用户换手机后，旧消息能恢复吗？

A: E2EE 开启时，换机后需要导入旧设备的密钥备份才能解密历史消息。见 E2EE 文档。

Q: 群组最多支持多少人？

A: 当前版本默认限制 500 人/群。可通过配置文件修改：

{max_group_members, 1000}

Q: 支持哪些消息类型？

A: 文字、图片、语音（录音）、视频、文件、位置、名片。

账号相关

Q: 忘记管理员密码怎么办？

A: 在 Erlang 控制台重置：

_rel/imboy/bin/imboy remote_console

# 重置管理员密码
user_logic:reset_password(<<"admin">>, <<"NewPassword123">>).

Q: 注册时收不到验证码？

A: 检查短信服务配置（IMBOY_SMS_* 环境变量）。本地开发环境验证码会打印到后端日志：

docker compose logs imboy | grep verification_code

开发相关

Q: 本地编译报 rebar3: command not found？

A: 安装 rebar3：

# macOS
brew install rebar3

# Linux
curl -fsSL https://s3.amazonaws.com/rebar3/rebar3 -o /usr/local/bin/rebar3
chmod +x /usr/local/bin/rebar3

Q: 运行 EUnit 测试时报数据库连接错误？

A: 确认本地 PostgreSQL 在运行：

docker compose -f deploy/docker-compose.dev.yml up -d postgres

Q: 如何查看当前有多少 WebSocket 连接？

A: 在 Erlang 控制台：

ws_user_server:count().

许可证相关

Q: License 到期后服务会停止吗？

A: 不会立即停止。License 支持 7 天宽限期（grace_period_days），期间服务正常运行，但会在日志和管理后台显示告警。宽限期结束后禁止新用户注册，现有用户不受影响。

Q: 如何购买商业 License？

A: 发邮件至 leeyisoft@qq.com，或通过 GitHub Issues 联系。

Clone this wiki locally