贡献指南 (Contributing)

欢迎参与 @kinkeeper 项目的开发！本文档记录了项目开发、部署过程中沉淀的经验与常见问题，帮助新加入的开发者避坑。

部署与环境常见坑 (Deployment & Environment Pitfalls)

在将项目部署到微信云托管以及配置阿里云资源时，经常会遇到以下几个典型问题：

1. 微信云托管一直在跑默认的 Node/MySQL 示例镜像

• 现象：部署日志或运行日志中频繁报 wxcloudrun-express@1.0.0 start /app，以及 SequelizeConnectionError: connect ETIMEDOUT（MySQL 连接超时）等不属于本项目的报错。
• 原因：本项目是 Monorepo 架构且没有使用 MySQL。微信云托管如果没识别对构建配置，或者服务设置里残留了默认模板的启动命令，会静默拉取官方的 Node.js + MySQL 示例镜像覆盖你的项目。
• 解决办法：
  1. 采用“代码库拉取”部署时，务必将 Dockerfile 路径 填写为 Dockerfile，构建上下文目录 填写为 .（即根目录，非常重要）。
  2. 在服务设置的“启动命令”中，必须清空默认填写的 npm start 或 node index.js（我们项目 Dockerfile 已内置了正确的 CMD 启动命令）。
  3. 如果发现旧的错误版本一直在重启，请前往“版本管理”中将报错的旧版本手动停用/下线。
  4. 如果流水线日志显示镜像已经成功构建（但实例没更新），可以在发布时选择“镜像部署”，直接选用腾讯云镜像仓库 (TCR) 中刚刚成功打包的镜像。

2. 阿里云表格存储 (OTS) 报错 ACL 策略拒绝

• 现象：后端服务启动成功（打印 Server running on port 80），但发起接口请求时控制台报错 OTSAuthFailed(Request denied by instance ACL policies)。
• 原因：阿里云 OTS 实例出于安全考虑，默认新建时可能限制了只允许 VPC（内网）访问。微信云托管与你的 OTS 实例不在同一个内网中，通过公网发起的请求会被阿里云防火墙拦截。
• 解决办法：进入阿里云控制台 -> 表格存储 -> 对应的实例，在实例概览中找到“网络安全”或“网络类型限制”设置，将其修改为 “允许任意网络访问”。

3. 阿里云表格存储 (OTS) 报错 table not exist

• 现象：网络请求报错 OTSParameterInvalidRequest table not exist。
• 原因：阿里云上的 OTS 实例是全新创建的空数据库实例，没有初始化业务所需的表结构。
• 解决办法：在本地环境配置好目标环境（测试/生产）的 AccessKey 和 Endpoint 变量（例如配置到 packages/server/.env.prod），然后手动执行建表脚本初始化数据库：

  # 进入 server 目录，指定对应环境执行初始化脚本
  cd packages/server
  NODE_ENV=production npx ts-node src/scripts/setup_ots.ts

  确保终端输出了各个表（users, reasons, records 等）创建成功的提示后，服务方可正常使用。

---

如果遇到新的坑，欢迎随时补充到本文档中！