jinmantiantang 问题排查指南

最常见的原因是安装路径中存在中文字符或空格，导致解析器把路径截断，找不到可执行文件。请检查安装目录是否形如 C:\jinmantiantang 安装\，如果是，请卸载后重新安装到纯英文路径，例如 C:\opt\jinmantiantang。

• 先执行完整卸载，清理残留环境变量
• 安装时避免使用「我的文档」「桌面」等含空格的默认目录
• 检查系统 PATH 变量是否被错误截断

这种情况通常是进程在等待某个锁文件或外部服务响应。jinmantiantang 首次启动时会检查本地锁文件和配置的端口占用情况，若上次非正常退出，锁文件可能残留。

• 进入安装目录下的 lock/ 文件夹，删除所有 .lock 后缀文件
• 执行 netstat -ano | findstr :端口号 确认端口未被占用
• 以管理员身份重新启动，观察控制台输出

如果以上操作后仍卡住，可在后台挂起 jinmantiantang 进程，观察其 I/O 活动，确认是否在读写某个磁盘路径。

无报错闪退多半是系统层面的拒绝，常见触发条件有两个：一是用户权限不足，二是安全软件将进程误判为风险行为。建议先用「资源监视器」观察进程在退出前的最后行为，定位是哪一步触发了终止。

• 以管理员身份运行，排除权限问题
• 将安装目录加入安全软件的白名单
• 开启调试模式启动：jinmantiantang --debug，此时会输出更详细的初始化阶段日志

jinmantiantang 在设计上会对高频数据做本地缓存，内存随使用时间缓慢增长属于正常现象。但当内存增长斜率明显超过每日 200MB 时，就需要介入干预了。

• 检查 cache.max_size 配置项，默认值过大会导致缓存积压
• 确认是否存在未释放的资源句柄，可通过性能计数器观察活跃连接数
• 对于长时运行场景，建议配置定时缓存刷新策略，每 6 小时重置一次

如果业务量确实在增长，适当调大内存上限比强行限制更稳妥，避免频繁换页带来更大的性能损失。

高并发下响应延迟通常来自三个瓶颈：线程池满、数据库连接不足、以及序列化阻塞。jinmantiantang 内部使用了固定大小线程池处理任务，线程池耗尽时会拒绝新请求或排队等待。

• 查看 thread_pool.size 配置，根据 CPU 核数调整为核数的 2-4 倍
• 检查数据库连接池是否有泄漏，启用连接超时时间并设置最大等待时间
• 开启请求队列限流，超出阈值时直接返回降级响应而非无限排队

建议在测试环境用压测工具模拟峰值流量，记录各组件的 CPU 和 I/O 曲线，找到真实瓶颈后再调整参数，不要一次性修改多个参数。

jinmantiantang 会将部分临时数据写入磁盘，包括请求日志、缓存文件和事务记录。当磁盘 I/O 长期高于 80%，通常意味着日志级别过高或磁盘本身性能不足。

• 将日志级别从 DEBUG 调整为 INFO，减少冗余日志输出
• 检查日志轮转策略，确认是否有日志文件未被压缩或删除
• 如使用机械硬盘，建议将缓存目录迁移至 SSD

配置文件格式正确但仍报错，通常是某个字段的值不在允许的范围内，或者引用了不存在的资源。 jinmantiantang 在启动时会做严格校验，校验失败的字段会在日志中以 [CONFIG ERROR] 开头标记。

• 搜索日志中的 [CONFIG ERROR] 关键词，定位具体字段名
• 对照官方文档确认该字段允许的值范围，某些枚举值大小写敏感
• 检查被引用的路径、端口、域名是否在当前环境中真实存在

对于不熟悉的配置项，建议先备份原始配置文件，再逐一修改并重启，这样能快速定位是哪个字段导致了问题。

jinmantiantang 的某些关键参数会优先读取环境变量，而非配置文件。当环境变量与配置文件冲突时，以环境变量为准，这在 CI/CD 流水线中尤为常见。

• 执行 env | grep JINMAN 查看当前环境中所有相关变量
• 检查启动脚本中是否有 export 语句覆盖了预期值
• 在容器化部署时，通过环境变量注入而非修改镜像内的配置文件

建立「环境变量 > 配置文件」的优先级意识，能在多人协作时减少大量排查时间。

多实例部署时，端口、数据目录和日志路径需要完全隔离，否则会出现端口冲突或数据串扰。 jinmantiantang 支持通过 --instance-id 参数指定实例标识，不同实例应使用不同的标识。

• 每个实例分配独立的端口段、数据目录和日志目录
• 使用容器化方案时，每个容器内只运行一个实例，避免在同一进程空间内共享资源
• 通过健康检查接口监控每个实例的状态，便于快速发现哪个实例出现异常

多实例场景下建议引入负载均衡器，让流量分发和实例管理更加可控。

连接超时有两种可能：一是自身网络出口不稳定，二是目标服务响应慢或不可达。区分两者的最简单方法是先用 curl 或 telnet 直接测试目标地址的连通性，绕过 jinmantiantang 自身逻辑。

• 执行 curl -v --max-time 10 目标地址，观察握手和响应时间
• 检查本机 DNS 解析是否正常，nslookup 目标域名确认解析结果
• 查看防火墙规则是否阻断了特定端口的出站连接

如果 curl 正常但 jinmantiantang 超时，问题大概率出在连接池配置或重试策略上，建议增大 connection.timeout 和 retry.count。

jinmantiantang 默认尊重系统代理环境变量，但如果程序内部使用了自定义 HTTP 客户端，可能需要单独配置代理。检查以下几点：

• 确认系统已设置 http_proxy 和 https_proxy 环境变量
• 查看 jinmantiantang 的 proxy.enabled 选项是否显式关闭
• 某些情况下程序会忽略系统代理，需在配置文件中显式指定代理地址

在企业内网环境中，建议统一通过配置文件管理代理设置，而非依赖环境变量，这样可以避免不同实例行为不一致。

写入成功但读取为空，是 jinmantiantang 最常见的一类数据不一致问题。根本原因通常有三个：缓存未及时刷新、事务未提交、或读写路径不一致。

• 检查写入操作是否包裹在事务中，且事务已正确提交
• 查看缓存 TTL 配置，确认是否设置了过长的过期时间导致读到旧数据
• 核对读写使用的存储路由是否一致，避免写入了 A 分片却从 B 分片读取

建议在关键业务中开启读写一致性模式，虽然会略微增加延迟，但能从根本上避免数据不一致带来的业务风险。更多关于数据一致性的配置选项，可以参考 实践方法 页面。