ImQi1-CMS 文档

本节汇总部署与开发过程中可能遇到的问题。如未列出所遇问题，请通过快速开始中的联系方式反馈，我会及时回复并补充本节内容。非本项目相关的问题请不要提交 Issues，也不要在 imqi1.com 的评论区询问。对于确实属于本文档或项目源码的问题，如已成功复现，除通过上述方式反馈外，也可以在 GitHub 提交。

如文档内容与源码不一致，请以源码为准，并确保所使用的代码与仓库的最新提交保持一致。项目以提交记录为准，而非 release；提交前均已完成可用性验证。

PostgreSQL 数据库相关

宝塔面板安装 PostgreSQL 失败，但提示成功

请先查看 /tmp/pgsql_install.log 和 /www/server/pgsql。

如果安装日志中存在 configure: error: bison not found，请继续阅读下文；如不存在该信息，则属于本文尚未覆盖的情况，请反馈给我，我会补充相关说明。

这是因为安装过程中缺少了 bison 工具，而安装脚本错误地继续执行并显示“安装成功”。

修复方法是先安装缺失依赖（Ubuntu 仓库自带 bison 和 flex）：

Bashapt-get install -y bison flex

然后在面板「软件商店 → PostgreSQL 管理器」中重新安装即可。

pgadmin 连接不到 PostgreSQL 数据库

快速部署介绍了通过 Docker 安装 pgadmin、通过 PostgreSQL 管理器安装 PostgreSQL 数据库的方式。其原因在于，pgadmin 位于容器内，而 PostgreSQL 安装在宿主机上，二者默认不在同一网络中。

首先查看 pgadmin 所在的网络位置。宝塔面板会将通过 Docker 应用安装的容器关联到同一个网络 baota_net：

Bashdocker network inspect baota_net | grep -oP '"Gateway":\s*"\K[^"]+'

查看 pgadmin 的 compose 配置即可确认：

YAMLservices:
  pgadmin_bBFi:
    image: dpage/pgadmin4:${VERSION}
    #    container_name: ${CONTAINER_NAME}
    deploy:
      resources:
        limits:
          cpus: ${CPUS}
          memory: ${MEMORY_LIMIT}
    restart: always
    environment:
      PGADMIN_DEFAULT_EMAIL: ${EMAIL}
      PGADMIN_DEFAULT_PASSWORD: ${PASSWORD}
    ports:
      - ${HOST_IP}:${WEB_HTTP_PORT}:80
    volumes:
      - ${APP_PATH}/data:/var/lib/pgadmin
    labels:
      createdBy: "bt_apps"
    networks:
      - baota_net

networks:
  baota_net:
    external: true

获取 IP 后，需要修改 PostgreSQL 的配置。路径为【软件商店】→【PostgreSQL 管理器】→【配置】，新增：

INIwork_mem = 8MB
effective_cache_size = 8GB
temp_buffers = 16MB
max_prepared_transactions = 0
max_stack_depth = 2MB
bgwriter_lru_maxpages = 100
max_worker_processes = 8
listen_addresses = '*'

然后在客户端认证中加一行：

INI# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             127.0.0.1/32            scram-sha-256
# IPv6 local connections:
host    all             all             ::1/128                 scram-sha-256
# Docker baota_net (pgAdmin) connections:
host    all             all             172.18.0.0/16           scram-sha-256  
# Allow replication connections from localhost, by a user with the
# replication privilege.
local   replication     all                                     trust
host    replication     all             127.0.0.1/32            scram-sha-256
host    replication     all             ::1/128                 scram-sha-256
host    demo   demo    0.0.0.0/0    md5
host    demo  demo    0.0.0.0/0    md5

更改后重启 PostgreSQL 数据库，即可在 pgadmin 中建立连接。

在 pgadmin 成功执行了导入脚本，但是项目查表显示无权限

...

Database error. Code: `42501`. Message: `permission denied for table trusted_devices`
at vn.handleRequestError (/www/wwwroot/glass/node_modules/@prisma/client/runtime/client.js:65:8643)
... 7 lines matching cause stack trace ...
at async Server.toNodeHandle (file:...) {
cause: PrismaClientKnownRequestError:
Invalid `prisma.trusted_devices.upsert()` invocation:
}

...

请确认初始化数据库时使用的登录用户与在宝塔面板中创建数据库时指定的用户一致。

1 / 5

确认上述用户名一致后，再导入数据库。

疑似 bug

部署成功后访问我自己的站点，会重定向到其他站点或 imqi1.com

检查构建时 site.config.ts 内的 _url 是否与站点完整 URL 不一致。

这是因为本项目有一个防镜像的客户端插件，在访客浏览器检测到当前域名不是 _url 对应的域名时，会自动跳转到 _url 定义的域名。将 _url 定义的值修改为你的站点的完整 URL 即可。

打包时服务器卡死，甚至影响正式业务

因为 Nuxt 打包服务端会占用大量 CPU，导致你的其他功能抢占不到 CPU 资源，造成卡死。

解决方法是更换为配置更高的服务器，或在本地计算机上完成构建。

如本地计算机在构建时同样出现卡死，应更换为配置更高的设备。

所有评论与足迹显示的都是同一个 IP，登录限流还会误伤全站

这是因为应用没有采信反向代理转发来的客户端地址。应用侧由 .env 中的 TRUSTED_PROXY 决定哪些回源地址可信，见 .env。回源地址不在白名单时，转发头会被丢弃，所有访客的 IP 都塌缩成反向代理的地址——评论入库的 IP 全一样、足迹去重把所有访客当成同一个人、登录限流的失败计数也合并到同一个地址上，一个人连续输错密码就能把全站的登录一起锁死。整个过程不报任何错误，只会静默失效。

Docker 部署时容器看到的回源地址是 Docker 网桥的网关地址而不是 127.0.0.1，且网段由 Docker 动态分配，填单个 IP 换一台机器就会失效，直接填网段即可；站点前面有云负载均衡或远程 nginx 时同理：

INITRUSTED_PROXY=172.16.0.0/12

宿主机上的 nginx 直接回源到本机（如宝塔裸机部署）时，回源地址是 127.0.0.1，属于本机回环地址，无须配置。注意它与 nginx 侧的 DEPLOY_TRUSTED_PROXY 是两个变量，前者决定应用是否采信转发头，后者决定 nginx 是否恢复真实 IP，含义不同。

初始化数据库后，第一次发布文章或评论报唯一约束冲突

Unique constraint failed on the constraint: `contents_pkey`

以旧版本脚本初始化的库，示例数据显式指定了主键值：示例文章的 cid 为 1，示例分类的 mid 为 1，示例评论的 coid 为 1。PostgreSQL 的 SERIAL 序列在显式指定主键插入时不会推进，仍停留在 1，因此初始化后第一次新建文章、独立页面、分类或标签，以及第一位访客发表评论时，都会与示例数据冲突。

失败的这一次已经让序列前进了一位，再发布一次即可成功。最新提交的 init-db.sql 已在种子数据后主动修正序列，全新初始化不会再遇到此问题；在此之前初始化、且尚未创建过任何内容的库，可以在 pgadmin 或 psql 中执行：

SQLSELECT setval(pg_get_serial_sequence('contents', 'cid'), (SELECT MAX("cid") FROM "contents"));
SELECT setval(pg_get_serial_sequence('metas', 'mid'), (SELECT MAX("mid") FROM "metas"));
SELECT setval(pg_get_serial_sequence('comments', 'coid'), (SELECT MAX("coid") FROM "comments"));

已正常发布过内容的库，序列早已越出示例数据的取值范围，无须处理。后台「数据备份与恢复」的导入功能在导入完成后会自动修正序列，通过该途径恢复的数据不受影响。

Firefox 访问时实况照片只显示静态图

实况照片内嵌的视频段大多是手机直出的 HEVC 编码，Firefox 不支持解码。前端检测到视频解码失败后会自动移除视频、退化为静态图，这是预期的降级行为，不是照片损坏；Chrome、Edge 等浏览器不受影响。若希望 Firefox 也能播放，可以先用 compress:livephoto 脚本把实况照片转码为 H.264 再上传，用法见辅助开发。

部分歌曲无法播放，提示加载失败后自动切到下一首

页脚音乐播放器通过 /api/meting 接口获取歌曲的播放直链。个别歌曲受版权或 VIP 限制，平台不会开放播放直链，接口返回 400 后播放器会自动切换到下一首，属平台限制而非 bug。

另有一种情况表现为「Firefox 下歌曲加载失败而 Chrome 正常」：媒体直链以 http 返回时，Chrome 会静默升级为 https 放行，Firefox 则严格按 CSP 拦截。项目已把 /api/meting 的重定向目标统一升级为 https，遇到时先把主站更新到最新提交即可。