常见问题

先记录问题发生时间、访问地址、操作步骤和页面原始错误信息，再选择对应章节。不要通过删除数据库、关闭证书校验或执行重置来跳过问题。

本文容器命令适用于安装部署中的交付方式，在部署目录执行；自定义部署请替换为实际服务名。

管理页面无法打开或登录失败

按以下顺序检查：

1. 地址和协议：默认管理入口为 https://<服务器IP>:81/，不是 HTTP，也不是业务网站的 443 入口。
2. 网络范围：客户端是否在允许访问管理端口的网段或 VPN 中，安全组和防火墙是否放行 81/tcp。
3. 容器状态：在服务器上执行 docker compose ps；异常时执行 docker compose logs --tail=100 hihttps。
4. 证书提示：初次自签证书不受信任与账号密码错误是不同问题。核实服务器身份后在受控网络完成初始化，正式使用时配置管理后台 HTTPS。
5. 账号：首次安装需创建管理员，没有通用的默认账号密码。已有用户使用创建时的邮箱登录，并确认未被禁用。

忘记密码时，请联系仍可登录的管理员处理；全部管理员均无法登录时，保全数据并联系支持人员。不要用 --reset 找回密码，它会删除完整应用数据。

看不到菜单或操作按钮

首先确认登录的是哪个账号。操作员默认不管理用户与设置，审计员以查看为主。让管理员核对角色、模块权限和数据可见范围，详见用户与权限。

不要为了显示按钮而共用管理员账号。证书申请按钮不可用还可能是未配置 CertCloud，并不一定是权限不足。

浏览器提示业务证书不受信任或域名不匹配

1. 确认使用的是证书覆盖的业务域名，而不是服务器 IP。
2. 在访问服务中检查 证书配置，确认已选择目标证书并保存，证书未过期、私钥及证书链完整。
3. 查看浏览器实际收到的证书，核对域名、序列号和到期时间；不要只看管理列表中的最新证书。
4. 检查 DNS、CDN、负载均衡和 A/AAAA 记录是否把连接送到了其他入口。
5. 私有 CA 证书需要在客户端建立信任；不要用跳过证书校验作为修复。

DNS 尚未切换时，可用快速上手中的 curl --resolve 示例单独验证 HiHTTPS 入口。

配置了 HTTPS，为什么 HTTP 没有跳转

选择 HTTPS 只配置对应的 HTTPS 入口，不会自动创建 HTTP 入口，也不会自动重定向。

当前访问服务表单不允许把本服务域名作为重定向目标，即使目标改用 HTTPS 或不同端口也会被拒绝。因此，不能照搬“新增同域名 HTTP 服务，再重定向到该域名 HTTPS 地址”的配置方法。需要保留原有 HTTP 跳转时，请由管理员核对现有入口的处理方式，或联系支持人员确认适合当前版本的方案；不要直接修改自动生成的代理配置。

网站返回 502 或访问超时

先区分请求是否到达 HiHTTPS：

1. 检查业务域名解析和入口端口放行情况，确认访问服务已启用。
2. 从 HiHTTPS 服务器直接检查后端服务的协议、地址和端口是否可用。前端 HTTPS 不代表后端一定使用 HTTPS，转发目标须与后端真实协议一致。
3. 检查后端是否只监听自身的 127.0.0.1、防火墙是否拒绝 HiHTTPS，以及应用是否正常运行。
4. 查看业务错误日志和应用日志，核对问题时间。
5. 按路径分流时，确认后端能处理转发后的路径。本页示例不会自动去掉 /api/ 等前缀。

页面返回错误并不总是代理问题，后端应用自身也可能返回错误状态；需结合日志和直连结果判断。

无法申请证书或一直未签发

申请按钮不可用或提交失败

• 请管理员在 设置 -> CertCloud 账号设置 配置有效、配套的 Auth ID 和 Auth Key。
• 确认服务器能访问配置的 CertCloud 地址；离线安装包不提供离线签发能力。
• 查看产品是否可申请，域名数量、类型、算法及组织是否符合该产品要求。
• 核对申请页的计费账户和套餐情况，并勾选同意订户协议。
• 提交后已有订单号时，先检查订单状态，不要连续重复申请。

等待域名验证

• DNS/CNAME：按订单返回的记录类型、主机记录和值配置，检查是否填重了域名后缀，并等待权威 DNS 生效。这类验证不要求业务 A/AAAA 记录指向 HiHTTPS。
• DNS 持久验证：检查记录是否仍存在、授权范围及验证值有效期是否适用，不能把历史验证通过视为永久有效。
• 文件验证：从外部网络访问订单要求的 URL，确认返回正确验证内容；仅本机可访问、返回登录页或错误页都不足以通过。

配置后在验证窗口点击 我已配置完成，检测一下，再查看状态。具体步骤见域名验证。

验证通过后仍未签发

根据产品要求检查组织审核等其他环节，并以订单显示的状态或错误为准。验证通过不代表所有产品立即签发。

已同步证书，为什么不能绑定到访问服务

依次检查：

1. 证书是否已签发，证书材料是否已经下载到本地。
2. 是否提示 缺少私钥。在证书行点击 更多 -> 导入私钥，提供原申请使用的配套私钥。
3. 证书是否覆盖服务填写的全部域名，是否选择了正确的算法位置；国际 TLS 与商密 SM2 的证书选项不同。
4. SM2 是否同时具备签名、加密两套证书和私钥。
5. 当前账号是否具有相应证书的可见和使用权限。

同步无法恢复丢失的私钥，也不能凭空生成与已有证书匹配的新私钥，详见私钥导入。

新证书已签发，但网站仍使用旧证书

“已签发”不等于已部署。按证书生效与热加载检查材料、绑定、服务启用状态和配置加载结果。

重点核对服务是否引用了历史版本、是否仍绑定另一条导入证书，以及访问是否经过其他 TLS 终止入口。重新建立客户端连接并对比实际证书，不要只刷新管理页面。

当前界面没有独立的历史版本回滚入口。需要处理历史绑定时请联系管理员或支持人员，不要直接操作运行目录中的证书文件。

自动续期不可用、暂停或没有更新网站

• 普通导入证书不自动续期，需要人工更新。
• CertCloud 产品需满足自动续期及域名验证条件，开关不可用时查看详情提示。
• 账号凭据、网络、文件验证入口发生变化后，重新检查续期条件。
• 更换为其他 CertCloud 账号会暂停原账号订单的自动续期；新账号不会自动接管旧订单。
• 新版本签发后仍要完成部署。自动续期开关打开不代表网站已更新，也不代表订阅服务期限自动延长。

证书临近到期时，不要只等待后台重试。查明失败原因，并安排人工申请、导入或更换绑定，完成客户端验证。

配置保存后不生效

1. 查看保存是否确实成功。表单里显示新值不等于运行配置已更新。
2. 确认服务已启用，入口端口未冲突，客户端访问的是正确域名和端口。
3. 查看页面提示与应用日志中的配置测试或加载错误；底层日志可能出现 nginx 或 Angie 名称。
4. 使用高级配置时，先检查最近新增的语法和指令作用范围，不要直接修改自动生成的配置文件。
5. 保存失败后核对原服务是否仍正常；恢复可用状态后，再逐项修改并验证。

访问控制拒绝了应该允许的请求

1. 确认目标服务绑定了正确规则，而不是同名或旧规则。
2. 检查 IP 规则顺序和末尾 all 的允许/拒绝设置。
3. 同时配置账号与 IP 时，核对选择的是 用户及IP 还是 用户或IP。
4. 有 CDN 或上游代理时，核对 HiHTTPS 实际识别的来源 IP。
5. 区分 HiHTTPS 的 Basic Auth 用户与管理后台用户，二者不是同一组账号。

修改后分别测试允许和拒绝的请求。不要把认证方式改成“用户或IP”只为消除报错，这可能扩大允许访问的范围。对照示例见访问控制。

Stream 规则已启用，但端口访问不通

1. 检查入站端口与后端地址、端口是否填写正确。
2. 核对客户端实际协议与规则一致，例如 TCP 请求不能只启用 UDP。
3. 检查宿主机是否监听入口，以及防火墙、安全组和 NAT 是否放通对应协议。
4. 从 HiHTTPS 服务器检查后端是否可达，再使用真正的业务客户端验证。
5. 检查应用日志中的配置加载结果。

UDP 不能只用 TCP 连通性检查验收。FTP 等有独立控制与数据连接的协议，还需配置完整的业务端口范围。

授权校验失败

执行 docker ps -a 和 docker compose logs --tail=100 hihttps，查看具体错误码：

错误码	处理方向
LICENSE_MISSING	配置有效的授权文件或授权码之一
LICENSE_MULTIPLE_SOURCES	核对配置，只保留一种授权来源
LICENSE_FILE_UNREADABLE	检查授权文件路径、类型、挂载和读取权限
LICENSE_FORMAT_INVALID	通过可信交付渠道重新取得完整、未被换行破坏的许可证
LICENSE_KEY_UNKNOWN / LICENSE_SIGNATURE_INVALID	联系支持人员确认许可证与镜像版本匹配，不要自行修改许可证
LICENSE_PRODUCT_MISMATCH	使用专门为 HiHTTPS 签发的授权
LICENSE_PAYLOAD_INVALID	请支持人员核对公司、授权编号及签发信息
LICENSE_STATE_WRITE_FAILED	按报错检查目录所有者、写入权限及文件系统状态

授权检查失败会阻止应用启动，因此也会影响业务服务。不要把授权报错误认为单纯的管理页面故障。

部署故障

错误	处理方向
SQLITE_DATA_UNSAFE / DEPLOYMENT_STATE_UNKNOWN	核对数据目录、权限、挂载和 Docker 状态，不要当作空库继续安装
RELEASE_IMAGE_SELECTION_FAILED	核对镜像版本与架构，避免目录中存在多个候选；需要时指定 --image-tag
RELEASE_SOURCE_INVALID / RELEASE_STAGE_*	检查镜像文件、读取权限和暂存空间，必要时重新取得完整交付包
RELEASE_DIRECTORY_UNSAFE	确保执行用户拥有部署目录，且其他用户不能随意写入
DEPLOY_ENV_CONFLICT	核对 .env 与旧 .env.deploy，保全并确认旧配置后处理，不盲目覆盖
DEPLOY_ENV_UNSAFE	检查配置路径、文件类型、所有者及权限，不使用软链接

需要更多信息时，在部署目录执行：

bash deploy.sh --diagnose

配置检查通过后会生成 diagnostic-*.txt。如果配置本身冲突或路径不安全，诊断也可能被拒绝，应先处理原始错误。

联系支持前准备什么

• HiHTTPS 版本、服务器架构和使用的部署方式。
• 问题发生时间、影响的服务、复现步骤和完整错误提示。
• 已执行的检查及结果，特别是配置变更前后差异。
• 脱敏后的相关日志或诊断报告。

不要发送 .env、许可证、密码、API Key、私钥或未加密备份。提交截图时检查输入框、地址栏和错误详情是否含有敏感信息。