LighthouseApp 技术文档

欢迎查阅 LighthouseApp 技术文档。本目录包含项目的架构设计、开发指南和故障排查信息。

📚 文档导航

Clash Meta 核心 (推荐阅读)

文档	说明	适用人群
架构文档	完整架构设计、数据流、关键决策	所有开发者
编译指南	本地编译步骤、环境配置、优化方法	核心开发者
故障排查	常见问题、日志分析、崩溃调试	测试/运维

CI/CD 工作流

文档	说明
GitHub Actions 说明	自动化构建、发布流程

🚀 快速开始

新开发者入门

1. 了解架构 (必读)

   • 阅读 CLASH_ARCHITECTURE.md
   • 理解 Dart → Android → Go 三层架构
   • 掌握 FFI 通信机制

2. 配置开发环境

   • 按照 CLASH_BUILD_GUIDE.md 配置环境
   • 编译第一个 Clash Core
   • 验证编译结果

3. 运行项目

   # 1. 获取代码
   git clone <repo-url>
   cd LighthouseApp
   
   # 2. 初始化子模块
   git submodule update --init --recursive
   
   # 3. 编译核心
   cd core
   make android-arm64
   
   # 4. 运行 Flutter
   cd ..
   flutter pub get
   flutter run
   

核心开发者

如果您需要修改 Clash Meta 核心:

1. 修改代码

   cd core
   vim lib_android.go  # 或其他核心文件
   

2. 本地测试

   make android-arm64
   flutter run
   

3. 提交 PR

   • CI/CD 会自动构建所有架构
   • 检查 Actions 页面的构建结果
   • 等待代码审查

🏗️ 架构速览

┌─────────────────────────────────────────────────────────────┐
│                   LighthouseApp                             │
├─────────────────────────────────────────────────────────────┤
│  Flutter/Dart Layer                                         │
│  └─ lib/app/services/clash_imp/                             │
│      ├─ kr_clash_imp.dart      (核心封装)                   │
│      ├─ clash_ffi.dart         (FFI 绑定)                   │
│      └─ clash_config_generator (配置生成)                   │
├─────────────────────────────────────────────────────────────┤
│  Android Native Layer                                       │
│  └─ android/app/src/main/kotlin/com/hiddify/hiddify/        │
│      ├─ bg/VPNService.kt       (VPN 服务)                   │
│      └─ bg/ClashService.kt     (Clash 服务)                 │
├─────────────────────────────────────────────────────────────┤
│  Go Core Layer                                              │
│  └─ core/                                                   │
│      ├─ Clash.Meta/            (Git 子模块)                 │
│      ├─ lib_android.go         (JNI 桥接)                   │
│      └─ libclash.so            (编译产物)                    │
└─────────────────────────────────────────────────────────────┘

详细架构请参考 CLASH_ARCHITECTURE.md

🔧 常见任务

编译核心

cd core

# 单个架构 (快速)
make android-arm64

# 所有架构 (发布)
make android-all

# 清理
make clean

# 验证
make verify

更新 Clash.Meta

cd core
make update  # 更新子模块到最新版本
make android-arm64  # 重新编译

调试问题

# 查看 Android 日志
adb logcat -s "A/Clash" "E/Clash"

# 查看编译详情
cd core
go build -v -x -buildmode=c-shared -o test.so .

# 验证 SO 文件
nm -D libclash.so | grep quickStart

📖 核心概念

1. FFI 并发安全

问题: Go 运行时初始化不是线程安全的

解决: 使用 Completer 实现初始化锁

Future<void> _ensureInitialized() async {
  if (_initialized) return;
  if (_initLock != null) {
    await _initLock!.future;  // ✅ 等待其他初始化
    return;
  }
  // ... 执行初始化
}

详见 CLASH_ARCHITECTURE.md § 并发安全保证

2. Service Isolate 架构

为什么需要?

• VPN 服务运行在后台
• 主 Isolate 可能被销毁
• 需要独立的 Dart 运行时

实现:

// ClashService.kt
serviceEngine = FlutterEngine(Application.application)
val entrypoint = DartExecutor.DartEntrypoint(..., "_clashService")
serviceEngine?.dartExecutor?.executeDartEntrypoint(entrypoint)

详见 CLASH_ARCHITECTURE.md § Service Isolate 架构

3. Android VPN 路由配置

关键: getAndroidVpnOptions() 返回 35+ 详细 CIDR 路由

为什么重要?

• 避免 PermissionMonitor error 22
• 支持 bypass-LAN
• 兼容模拟器

详见 CLASH_TROUBLESHOOTING.md § 问题 1

🐛 遇到问题?

1. 查看故障排查文档

   • CLASH_TROUBLESHOOTING.md 包含所有常见问题

2. 收集诊断信息

   # 系统信息
   adb shell "getprop ro.build.version.release"
   
   # 应用日志
   adb logcat -d > full_log.txt
   
   # 核心信息
   cd core
   make verify
   

3. 提交 Issue

   • 使用诊断信息模板
   • 包含复现步骤
   • 附上日志文件

🤝 贡献指南

代码规范

项目遵循以下原则:

• KISS (Keep It Simple, Stupid) - 简单至上
• DRY (Don't Repeat Yourself) - 杜绝重复
• SOLID - 面向对象设计原则
• YAGNI (You Aren't Gonna Need It) - 精益求精

提交流程

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/amazing)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送分支 (git push origin feature/amazing)
5. 创建 Pull Request

Commit 规范

使用 Conventional Commits:

• feat: 新功能
• fix: 修复 Bug
• docs: 文档更新
• refactor: 代码重构
• perf: 性能优化
• test: 测试相关
• chore: 构建/工具链

📞 获取帮助

• GitHub Issues: 提交问题
• 文档索引: 您正在阅读!
• 外部资源:
  • Clash Meta Wiki
  • Flutter FFI 文档
  • Android VPN 指南

📝 更新日志

日期	版本	更新内容
2025-10-25	1.0.0	完成 Xboard-Mihomo 核心集成
2025-10-25	1.0.0	修复 FFI 并发安全问题
2025-10-25	1.0.0	添加完整技术文档

📄 许可证

本项目采用 LICENSE 许可证。

---

最后更新: 2025-10-25 维护者: LighthouseApp 开发团队