# 服务问题排查指引

## 服务运行中问题

### 一段时间不访问服务后，发现访问不通或访问速度明显变慢。再次访问后恢复/控制台服务状态显示：0 个实例（自动暂停）或服务启动中/报错："connect ECONNREFUSED"或"SERVICE_NOT_READY"

- 「服务设置」中，实例副本数最小值为 0 时，需要注意半小时无请求服务将缩容到 0，服务自动暂停，最大程度节约资源。再次请求时将重启服务，扩容新的实例。重启过程中的请求会报错："connect ECONNREFUSED"或"SERVICE_NOT_READY"，控制台服务状态显示为"服务启动中"。
- 服务从 0 扩容到 1（冷启动）耗时由服务启动速度决定，请尽可能优化服务启动性能。
- 如果你想彻底避免服务冷启动影响，到「服务设置」中将「实例副本数」最小值设为 1，但会持续产生资源消耗，请根据业务状态自行权衡。

### 服务运行中向容器写入的文件，过一段时间就不见了。

容器不支持持久化存储，请勿将图片、视频等文件直接存储在容器中，容器扩缩容/重启自愈时，这些写入的文件会被还原。请使用「对象存储」管理文件。

### 容器中时间跟本地时间相差 8 小时。

容器默认时区为 UTC，如需使用上海时间，请参考[官方模板](/minigame/dev/wxcloudrun/src/quickstart/template/official)中的 Dockerfile，启用时区设置命令。

注意：使用无 Dockerfile 模式部署，暂时不支持修改时区，只能用默认时区。

### 仍然使用 sns、jscode2session、getAccessToken 类接口，自行维护 access_token 时，请求 api.weixin.qq.com 超时/报错 502。

因项目迁移无暇改造为云调用方式，请关闭「开放接口服务」开关，然后重新部署使配置生效。

「开放接口服务」开关开启时，默认将使用云调用方式，因此可能引发链路超时或报错。

### 服务概率性出现 500 报错（排除各种代码错误后）

在「服务监控」中检查 CPU 使用率/内存使用率是否过高，甚至内存溢出 OOM。

- 所选容器规格过小，请调大规格。如果规格设置过低导致一个容器实例连 1 个请求都支撑不了（本身系统基础逻辑就很重），可能会导致部署成功但出现 500 错误。Java 服务相对较重，建议使用 1 核 2G 及以上规格。
- 设置的「扩缩容条件」不合适，比如设置的是 CPU 使用率大于 60% 扩容，但 CPU 未达标时内存使用已满。建议内存消耗大于 CPU 的服务，使用内存使用率作为扩缩容条件。

### 调用 https://api.weixin.qq.com 报 PKIX path building failed/Error: self signed certificate / x509: certificate signed by unknown authority

参见[云调用常见问题-证书相关](../weixin/faq#证书问题，常见表现：Error-self-signed-certificate-x509-certificate-signed-by-unknown-authority)

## 部署失败问题

### 本地运行正常，部署到云托管后却部署失败？

本地调试请尽量基于本地 Docker 进行，具体可参考[本地调试](/minigame/dev/wxcloudrun/src/guide/debug/index) 文档。

如果未基于本地 Docker 进行调试，直接转到云托管部署时可能遇到以下情况：

1. 本地运行的时候，各种依赖组件、扩展在本地都是齐全的，但是**没有在 Dockerfile 正确添加依赖安装命令**，所以本地运行时不缺依赖没问题，部署到云托管上时就会因为缺乏依赖导致报错。
2. 本地运行的时候，连接的是本地数据库（地址为本机 IP 或 localhost），部署到云托管上时**没有将数据库地址改为云上的数据库地址**。导致因为数据库无法连接而部署失败。
3. 本地使用的运行时环境（JDK/python 版本等），与 Dockerfile 中定义的运行时环境不一致。

### Readiness probe failed: dial tcp xx.xx.xx.xx:xxx: connect: connection refused

无法通过健康检查/端口调用不通。

- 服务启动正常，但是**端口填写错误**，真实端口与发布时填写端口不符，导致系统误认为部署失败。
- 服务启动成功，但反复重启，进程不稳定，导致端口无法稳定调通，无法通过健康检查。请自行结合日志排查代码问题，或考虑是否因为所选容器规格过小导致内存 OOM。
- 如果你的 Dockerfile 中包含了多行独立的 CMD 命令，请注意这是错误的写法！只有最后一行 CMD 命令会被执行，之前的都会被忽略，导致业务报错。请参考[Docker 官方文档之 CMD 命令](https://docs.docker.com/engine/reference/builder/#cmd)

### 部署失败但看业务日志已经在正常运行

- 检查服务设置中端口与真实项目端口是否一致。如果服务启动正常，但是**端口填写错误**，真实端口与发布时填写端口不符，会导致系统误认为部署失败，调用服务也会报错。
- 如端口确认填写无问题，可在用户群或[开发者社区](https://developers.weixin.qq.com/community/minihome/mixflow/1919566493118201863)提问或提交工单「[云托管控制台](https://cloud.weixin.qq.com/cloudrun/settings/env)-帮助-新建工单」。

### check pod status is not ok

- 服务因代码原因反复重启，状态不稳定。请自行排查代码问题。
- 尝试取消部署后重试。
- 若服务并未反复重启，请提工单联系我们排查。

### Back-off restarting failed container

代码原因导致服务启动失败，请借助服务日志自行排查代码问题，或参考[本地调试](/minigame/dev/wxcloudrun/src/guide/debug/index) 文档。没有采集到服务日志，请检查「服务设置」-「基础信息」-「日志采集路径」是否配置正确。

### 自行下载/拷贝了官方模板后上传部署失败（非通过控制台直接模板部署）

手动新建一个服务并部署模板代码，需要在「服务设置」中补全以下环境变量，才可正常使用，否则会引发无法连接数据库，进而导致部署失败。

MYSQL_ADDRESS

MYSQL_PASSWORD

MYSQL_USERNAME

以上三个变量的值请按实际情况填写。如果使用云托管内 MySQL，可以在控制台 MySQL 页面获取相关信息。

### 部署 eggjs 服务，运行 npm run start 不停重复启动

需要去掉进程守护参数 --daemon

更改前："start": "egg-scripts start --daemon --title=node-server",

更改后："start": "egg-scripts start --title=node-server"

### Dockerfile 中引用了环境变量不生效

构建/部署阶段，服务还未就绪，此时无法引用环境变量。

### Dockerfile 中引用了 MySQL 内网地址不生效

构建/部署阶段，服务还未就绪，此时无法通过内网地址访问 MySQL。

### 使用了云调用/开放接口服务报错

请参考[云调用常见问题](/minigame/dev/wxcloudrun/src/guide/weixin/faq) 文档。

### Cannot read -C 'conf/nginx.conf' (relative to '/workspace')

无 Dockerfile 模式部署 PHP 服务时，请确保在代码仓库的 conf 文件夹中存在 nginx.conf 文件。可参考[官方模板](https://github.com/WeixinCloud/wxcloudrun-thinkphp-nginx/blob/main/conf/nginx.conf) 。

### err=[ResourceUnavailable.ClusterInAbnormalStat][err=cloudrun cluster state is invalid(cluster state is deleted)

底层异常，请先尝试重新部署/删除服务后重新创建。如果还不能解决，请提工单联系我们处理。

### errMsg="CheckCloudBaseRunVpcDownVpc service status=create_fail"

底层异常，请先尝试重新部署/删除服务后重新创建。如果还不能解决，请提工单联系我们处理。

### DescribeCloudBaseRunServerVersion cluster not create

底层异常，请先尝试重新部署/删除服务后重新创建。如果还不能解决，请提工单联系我们处理。

### Insufficient account balance

当前账号已欠费，请冲正后重试。

### 部署 Docker Compose 失败

微信云托管不支持 Docker Compose。

## 构建失败问题

构建阶段问题多数为 docker 报错，绝大部分是因为没有正确配置 Dockerfile。

可参考[构建案例集合](/minigame/dev/wxcloudrun/src/scene/build/template) ,以及[如何提高项目构建效率](/minigame/dev/wxcloudrun/src/scene/build/speed)。或在网上搜索 docker 相关解决方案及教程。

### network connection aborted.

因为访问国外网络不稳定的不可抗力因素，建议尽量选用国内站作为镜像源下载依赖和扩展。具体可参考[官方模板](/minigame/dev/wxcloudrun/src/quickstart/template/official) 中的 Dockerfile 写法。

### 缺少依赖报错。例如：

> - java.lang.NoClassDefFoundError: Could not initialize class xxx

Dockerfile 中缺少对应的依赖安装命令。

建议优先换用更完整的构建用基础镜像而非直接增加依赖安装命令 (RUN apk xxx)，更加简单方便，且可以提高构建速度。

请到[dockerhub 官方仓库](https://hub.docker.com/_/java?tab=tags)自行选择合适的基础镜像（默认已包含了所有你需要的依赖），然后在 Dockerfile 中替换"FROM xxxxx as build" 命令。

### xxxxxx: no such file or directory

- 确保代码仓库/代码包中确实存在该文件且路径正确；
- 确保'.gitignore'或者'.dockerignore'中，没有包含这个文件——如果包含将会被构建忽略。去除即可。
- 确保 Dockerfile 中的 COPY 命令，拷贝文件的时候没有修改原有的文件路径。

### 无报错日志，空白

大概率是构建超时（> 10 分钟）。可参考文档[如何提高项目构建效率](/minigame/dev/wxcloudrun/src/scene/build/speed)。

## 流水线问题

### 执行流水线失败

* 请尝试重新授权代码仓库。
* 检查对应腾讯云账号下的 Coding DevOps ( https://console.cloud.tencent.com/coding ) ，确认没有误删除掉 cloudbase 开头的团队。如已误删除，可以提交工单寻求协助恢复

### push 代码但未触发构建

- 检查「服务设置-流水线」中是否开启 push 触发构建，且分支是否匹配
- 检查是否误删 Git 平台 webhook 是否存在，如 webhook 存在，请查看最近一次回调详情，排查回调是否正常

| Git 平台   | webhook 查看       | 回调详情查看              |
| :--------- | :--------- | :---------------- |
| Gitee       | ![](https://res.wx.qq.com/op_res/KueKykGa7vnAUMT9qN_6aAQuYE7qYaGqGu6T3coCDzKOSJJsxZ6SVgkM7oFbM2ZJVLaw5coLlM2A0P-9F3UG3g)  | ![](https://res.wx.qq.com/op_res/KueKykGa7vnAUMT9qN_6aMnseOGrFcYKp6Bz8pMBigQsP7pYh3hSedcoHermYdl3jfP1M2HyKxMflMkp9672IQ) |
| GitHub | ![](https://res.wx.qq.com/op_res/KueKykGa7vnAUMT9qN_6aLoKwPR3IY6SnCsw7WKq7ITt3LNT_GajJNbcjOjSIzQVnQIEib4SE0XAoqJ8RDtNxQ) | ![](https://res.wx.qq.com/op_res/KueKykGa7vnAUMT9qN_6aHQJH6HWvnXz0BgJSVlCPDtaKyJmW2RGhjllq3VV9bHUWyqn87Gr8-hyD3R2QL5tAw) |

- 如以上检查均无问题，可前往开发者社区、用户群反馈，也可提交工单