Rust
d02eed3bd8
- 添加完整的 GitHub Actions 构建指南文档 - BUILD_GUIDE.md: Android 详细构建指南 - MULTIPLATFORM_GUIDE.md: 多平台构建指南 - HOW_TO_BUILD.md: 分步操作教程 - QUICKSTART.md: 3步快速开始指南 - INDEX.md: 文档总览索引 - README.md: 基础说明 - 创建 docs/ 目录存放项目文档 - 锁定 libcore 子模块到 f993a57 (v3.1.7) - 防止在线编译时使用最新版本 - 确保构建稳定性和一致性
270 lines
7.5 KiB
Markdown
270 lines
7.5 KiB
Markdown
# LighthouseApp 技术文档
|
|
|
|
欢迎查阅 LighthouseApp 技术文档。本目录包含项目的架构设计、开发指南和故障排查信息。
|
|
|
|
## 📚 文档导航
|
|
|
|
### Clash Meta 核心 (推荐阅读)
|
|
|
|
| 文档 | 说明 | 适用人群 |
|
|
|------|------|----------|
|
|
| [**架构文档**](./CLASH_ARCHITECTURE.md) | 完整架构设计、数据流、关键决策 | 所有开发者 |
|
|
| [**编译指南**](./CLASH_BUILD_GUIDE.md) | 本地编译步骤、环境配置、优化方法 | 核心开发者 |
|
|
| [**故障排查**](./CLASH_TROUBLESHOOTING.md) | 常见问题、日志分析、崩溃调试 | 测试/运维 |
|
|
|
|
### CI/CD 工作流
|
|
|
|
| 文档 | 说明 |
|
|
|------|------|
|
|
| [**GitHub Actions 说明**](../.github/workflows/README.md) | 自动化构建、发布流程 |
|
|
|
|
## 🚀 快速开始
|
|
|
|
### 新开发者入门
|
|
|
|
1. **了解架构** (必读)
|
|
- 阅读 [CLASH_ARCHITECTURE.md](./CLASH_ARCHITECTURE.md)
|
|
- 理解 Dart → Android → Go 三层架构
|
|
- 掌握 FFI 通信机制
|
|
|
|
2. **配置开发环境**
|
|
- 按照 [CLASH_BUILD_GUIDE.md](./CLASH_BUILD_GUIDE.md) 配置环境
|
|
- 编译第一个 Clash Core
|
|
- 验证编译结果
|
|
|
|
3. **运行项目**
|
|
```bash
|
|
# 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. **修改代码**
|
|
```bash
|
|
cd core
|
|
vim lib_android.go # 或其他核心文件
|
|
```
|
|
|
|
2. **本地测试**
|
|
```bash
|
|
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](./CLASH_ARCHITECTURE.md)
|
|
|
|
## 🔧 常见任务
|
|
|
|
### 编译核心
|
|
|
|
```bash
|
|
cd core
|
|
|
|
# 单个架构 (快速)
|
|
make android-arm64
|
|
|
|
# 所有架构 (发布)
|
|
make android-all
|
|
|
|
# 清理
|
|
make clean
|
|
|
|
# 验证
|
|
make verify
|
|
```
|
|
|
|
### 更新 Clash.Meta
|
|
|
|
```bash
|
|
cd core
|
|
make update # 更新子模块到最新版本
|
|
make android-arm64 # 重新编译
|
|
```
|
|
|
|
### 调试问题
|
|
|
|
```bash
|
|
# 查看 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` 实现初始化锁
|
|
|
|
```dart
|
|
Future<void> _ensureInitialized() async {
|
|
if (_initialized) return;
|
|
if (_initLock != null) {
|
|
await _initLock!.future; // ✅ 等待其他初始化
|
|
return;
|
|
}
|
|
// ... 执行初始化
|
|
}
|
|
```
|
|
|
|
详见 [CLASH_ARCHITECTURE.md § 并发安全保证](./CLASH_ARCHITECTURE.md#并发安全保证)
|
|
|
|
### 2. Service Isolate 架构
|
|
|
|
**为什么需要?**
|
|
- VPN 服务运行在后台
|
|
- 主 Isolate 可能被销毁
|
|
- 需要独立的 Dart 运行时
|
|
|
|
**实现:**
|
|
```kotlin
|
|
// ClashService.kt
|
|
serviceEngine = FlutterEngine(Application.application)
|
|
val entrypoint = DartExecutor.DartEntrypoint(..., "_clashService")
|
|
serviceEngine?.dartExecutor?.executeDartEntrypoint(entrypoint)
|
|
```
|
|
|
|
详见 [CLASH_ARCHITECTURE.md § Service Isolate 架构](./CLASH_ARCHITECTURE.md#2-android-service-层-clashservicekt)
|
|
|
|
### 3. Android VPN 路由配置
|
|
|
|
**关键:** `getAndroidVpnOptions()` 返回 35+ 详细 CIDR 路由
|
|
|
|
**为什么重要?**
|
|
- 避免 PermissionMonitor error 22
|
|
- 支持 bypass-LAN
|
|
- 兼容模拟器
|
|
|
|
详见 [CLASH_TROUBLESHOOTING.md § 问题 1](./CLASH_TROUBLESHOOTING.md#问题-1-vpn-连接失败日志显示-permissionmonitor-error-22-einval)
|
|
|
|
## 🐛 遇到问题?
|
|
|
|
1. **查看故障排查文档**
|
|
- [CLASH_TROUBLESHOOTING.md](./CLASH_TROUBLESHOOTING.md) 包含所有常见问题
|
|
|
|
2. **收集诊断信息**
|
|
```bash
|
|
# 系统信息
|
|
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:** [提交问题](https://github.com/your-repo/issues)
|
|
- **文档索引:** 您正在阅读!
|
|
- **外部资源:**
|
|
- [Clash Meta Wiki](https://wiki.metacubex.one/)
|
|
- [Flutter FFI 文档](https://dart.dev/guides/libraries/c-interop)
|
|
- [Android VPN 指南](https://developer.android.com/reference/android/net/VpnService)
|
|
|
|
## 📝 更新日志
|
|
|
|
| 日期 | 版本 | 更新内容 |
|
|
|------|------|----------|
|
|
| 2025-10-25 | 1.0.0 | 完成 Xboard-Mihomo 核心集成 |
|
|
| 2025-10-25 | 1.0.0 | 修复 FFI 并发安全问题 |
|
|
| 2025-10-25 | 1.0.0 | 添加完整技术文档 |
|
|
|
|
## 📄 许可证
|
|
|
|
本项目采用 [LICENSE](../LICENSE) 许可证。
|
|
|
|
---
|
|
|
|
**最后更新:** 2025-10-25
|
|
**维护者:** LighthouseApp 开发团队
|