故障排除指南

本文档帮助你解决使用 lzt 时可能遇到的常见问题。

🔧 安装和配置问题

找不到命令

问题: 运行 lzt 时提示 "command not found"

解决方法:

# 检查是否在 PATH 中
which lzt
echo $PATH

# 如果不在 PATH，添加到 shell 配置
echo 'export PATH="$PATH:/path/to/lzt"' >> ~/.bashrc
source ~/.bashrc  # 或重启终端

权限错误

问题: 运行时提示权限被拒绝

解决方法:

# 给予执行权限
chmod +x lzt

# 如果需要写入配置目录
mkdir -p ~/.config/lzt
chmod 755 ~/.config/lzt

Go 版本过低

问题: 编译时提示 Go 版本不兼容

解决方法:

# 检查当前版本
go version

# 更新到 Go 1.24.3 或更高版本
# 访问 https://golang.org/dl/ 下载最新版本

🗄️ 数据库连接问题

连接超时

问题: 数据库连接超时或失败

诊断步骤:

# 1. 检查数据库服务状态
mysql -u your_user -p -h localhost -e "SELECT 1"

# 2. 检查配置文件
cat ~/.lzt.yaml | grep -A 10 "db:"

# 3. 测试连接
lzt ledger init --help  # 仅测试配置解析

解决方法:

# ~/.lzt.yaml
db:
  user: "correct_username"
  pwd: "correct_password"
  host: "127.0.0.1"  # 尝试 IP 而不是 localhost
  port: 3306
  name: "correct_database"
  write_timeout: 600  # 增加超时时间
  read_timeout: 600

表不存在

问题: 提示 ledger 相关表不存在

解决方法:

# 运行初始化命令创建表
lzt ledger init

# 手动创建表（如果自动创建失败）
mysql -u user -p database < docs/schema.sql

权限不足

问题: 数据库用户权限不足

解决方法:

-- 给予必要权限
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER ON database_name.* TO 'username'@'localhost';
FLUSH PRIVILEGES;

🌐 API 集成问题

gRPC API 错误

问题: gRPC API 调用失败

常见错误码:

错误码	说明	解决方法
UNAVAILABLE	服务不可用	检查服务是否启动
UNAUTHENTICATED	认证失败	检查认证配置
DEADLINE_EXCEEDED	请求超时	增加超时时间或检查网络

诊断命令:

# 测试 gRPC 服务
grpcurl -plaintext localhost:8080 list

# 检查服务状态
lzt ledger server --port 8080

Magento GraphQL 问题

问题: GraphQL 请求失败

解决方法:

# 测试 GraphQL 端点
curl -X POST https://your-site.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT" \
  -d '{"query":"query { __typename }"}'

# 检查 JWT token 有效性
# JWT token 通常有过期时间，需要定期更新

🎨 终端 UI 问题

颜色显示异常

问题: 进度条或界面颜色显示不正确

解决方法:

# 设置色彩支持
export COLORTERM=truecolor
export TERM=xterm-256color

# 对于 tmux 用户
export TERM=screen-256color

# 重新运行命令
lzt example tea worker

界面布局错乱

问题: 终端界面显示混乱

解决方法:

# 检查终端大小
echo "终端大小: $(tput cols)x$(tput lines)"

# 确保终端足够大（建议最小 80x24）
# 调整终端窗口大小后重新运行

# 清理终端
clear
lzt example tea worker

中文显示乱码

问题: 中文字符显示为乱码

解决方法:

# 设置 UTF-8 编码
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

# 或者中文环境
export LC_ALL=zh_CN.UTF-8
export LANG=zh_CN.UTF-8

🧩 Bubble Tea 组件专项故障排除

复合进度条同步问题

问题: CompositeProgressModel 主进度条在所有子任务完成时显示不正确的百分比（如 96% 或 93%），而不是期望的 100%

症状表现:

• example tea composite 显示 96% 而非 100%
• example tea simple-api --mode=composite 显示 93% 而非 100%
• 文本百分比显示正确：4/4子任务 100.0%
• 进度条视觉效果错误：显示为未完成状态

根因分析:

• Bubble Tea 进度条组件异步特性：progress.Model.SetPercent() 方法是异步的，通过消息循环更新
• 进度条状态不同步：progress.Model.View() 方法可能返回未完成更新的旧值
• 异步更新延迟：渲染时机与进度更新时机不同步

解决方案:

核心修复策略：使用 ViewAs() 方法强制同步

1. 主进度条同步修复（文件：pkg/bubble/composite.go，约第 603 行）：

   // 修复前
   progressBar := m.mainProgress.View()
   
   // 修复后
   // **关键修复**：直接使用 ViewAs() 确保进度条显示与 lastSetProgress 同步
   progressBar := m.mainProgress.ViewAs(m.lastSetProgress)

2. 子任务进度条同步修复（文件：pkg/bubble/composite.go，约第 540 行）：

   // 修复前
   progressBar := state.Progress.View()
   
   // 修复后
   // 使用 ViewAs() 确保子任务进度条显示与当前进度同步
   progressBar := state.Progress.ViewAs(currentProgress)

验证方法:

# 运行所有复合进度条测试
go test ./pkg/bubble -v

# 运行特定的同步测试
go test ./pkg/bubble -v -run TestRealScenarioProgressTextDisplay

# 验证实际命令效果
go run main.go example tea composite
go run main.go example tea simple-api --mode=composite

其他 Bubble Tea 常见问题

进度条显示为空条:

• 原因: 使用了 View() 而非 ViewAs()
• 解决: 检查 lastSetProgress 是否正确设置，使用 ViewAs() 强制同步

文本百分比正确但进度条错误:

• 原因: 异步更新问题
• 解决: 使用 ViewAs() 强制同步

测试通过但实际命令有问题:

• 原因: 测试环境与实际运行环境的差异
• 解决: 需要模拟完整的消息循环流程

⚡ 性能问题

测试执行慢的问题

问题: 执行 go test ./... -v 时，测试运行时间过长或卡住

推荐解决方案:

# ✅ 推荐：使用分组测试，提高执行效率
go test -v ./pkg/...              # 测试核心包
go test -v ./internal/...         # 测试内部包  
go test -v ./testing/performance/... # 测试性能包

# 或使用项目提供的快速测试脚本
.act-artifacts/quick-test.sh

性能优化:

• 项目已优化测试策略，分组执行避免超时
• 使用 Mock 服务器提高测试速度
• 总测试时间控制在 2 分钟内

处理速度过慢

问题: 数据处理速度很慢

优化建议:

# 1. 调整并发数（根据系统性能）
lzt example tea simple-api --mode=concurrent

# 2. 检查系统资源
top
htop  # 如果已安装

# 3. 优化数据库
# 确保相关字段已建立索引
# 定期运行 ANALYZE TABLE

内存使用过高

问题: 程序占用内存过多

解决方法:

# 使用内存优化模式
lzt example tea simple-api --mode=memory

# 降低并发数
lzt example tea simple-api --mode=concurrent

# 监控内存使用
ps aux | grep lzt

📁 配置文件问题

配置文件语法错误

问题: YAML 配置文件格式错误

检查方法:

# 验证 YAML 语法
python3 -c "import yaml; yaml.safe_load(open('~/.lzt.yaml'))"

# 或使用在线 YAML 验证器

常见错误:

# ❌ 错误：缩进不一致
db:
  user: "username"
    pwd: "password"  # 缩进错误

# ✅ 正确：统一缩进
db:
  user: "username"
  pwd: "password"

环境变量优先级

问题: 配置文件设置被环境变量覆盖

调试方法:

# 查看所有 LINNZH_CLI 相关环境变量
env | grep LINNZH_CLI

# 清除环境变量（临时）
unset LZ_STASH_

# 或显式指定配置文件
lzt --config=/path/to/config.yaml ledger init

🔍 日志和调试

启用详细日志

# 增加日志详细程度
export LZ_STASH_LOG_LEVEL=debug

# 重定向日志到文件
lzt ledger server 2>&1 | tee lzt.log

常见日志模式

正常运行:

[INFO] 开始初始化 ledger 数据库...
[INFO] 正在执行数据库迁移...
[INFO] 成功创建账本管理相关表结构

连接问题:

[ERROR] failed to ping database within 5 seconds: dial tcp 127.0.0.1:3306: connect: connection refused

gRPC 服务问题:

[ERROR] gRPC server error: rpc error: code = Unavailable
[ERROR] 启动 gRPC 服务失败: failed to listen on port 8080

🚀 部署和开发问题

文档部署失败

问题: Cloudflare Pages 或其他静态站点部署失败

常见错误:

➤ YN0028: │ The lockfile would have been modified by this install, which is explicitly forbidden.
Error: Exit with error code: 1

解决方案: 查看专门的 部署故障排除指南，包含：

• Yarn/npm 版本冲突解决
• Package.json 配置优化
• 多包管理器兼容性设置
• VitePress 构建问题修复

本地开发环境问题

问题: 文档服务无法启动

解决方法:

# 检查 Node.js 版本
node --version  # 需要 >= 18

# 安装依赖
npm install
# 或
yarn install

# 启动开发服务器
npm run docs:dev
# 或
yarn docs:dev

CI/CD 流水线问题

问题: GitHub Actions 构建失败

解决方法: 参考 CI/CD 系统文档 了解：

• 工作流架构和触发条件
• 测试覆盖率要求
• 多平台构建配置
• 发布流程故障排除

🆘 获取帮助

自助诊断

1. 检查版本: lzt --version
2. 查看帮助: lzt command --help
3. 测试基础功能: lzt example tea worker
4. 验证配置: lzt --config ~/.lzt.yaml --help

报告问题

如果问题仍然存在，请收集以下信息：

# 系统信息
uname -a
go version
lzt --version

# 配置信息（请移除敏感数据）
cat ~/.lzt.yaml

# 错误日志
lzt your-command 2>&1 | tee error.log

社区支持

• GitHub Issues: 报告 Bug
• GitHub Discussions: 技术讨论
• 文档: 项目文档

📝 常见问题快速参考

问题类型	快速检查	解决命令
命令找不到	which lzt	chmod +x lzt
数据库连接	mysql -u user -p -h host	检查配置文件
gRPC 服务	grpcurl -plaintext localhost:8080 list	启动服务
颜色显示	echo $COLORTERM	export COLORTERM=truecolor
性能问题	top	使用内存优化模式
进度条同步	检查是否使用 View()	改用 ViewAs()

💡 最佳实践

开发调试

• 使用详细日志排查问题
• 运行相关测试验证修复
• 本地验证后再提交代码

生产环境

• 定期检查日志异常
• 监控性能指标
• 备份重要配置和数据

社区贡献

• 遇到新问题时记录解决过程
• 完善测试用例覆盖边界情况
• 更新文档帮助其他用户

快速恢复

大多数问题可以通过重新安装和重置配置文件解决：

rm ~/.lzt.yaml
go install github.com/FixIterate/lz-stash

---

💡 提示: 本故障排除指南会持续更新，如果您遇到新的问题或有更好的解决方案，欢迎贡献到项目文档中。