Update: Build scripts and project documentation - 2026-04-03 19:05:44

2026-04-03 19:05:44 +08:00
parent 0f4fe33003
commit b9750b5ba3
5 changed files with 408 additions and 1 deletions
--- a/BUILD_GUIDE.md
+++ b/BUILD_GUIDE.md
@@ -0,0 +1,132 @@
+# 构建指南
+
+## 环境要求
+
+- Flutter SDK 3.29+
+- Dart 3.11+
+- Android SDK
+- Java 17+
+
+## 快速开始
+
+### 1. 安装 Flutter
+
+```bash
+# 下载 Flutter SDK
+cd /tmp
+curl -o flutter_linux.tar.xz "https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.29.0-stable.tar.xz"
+
+# 解压到 /opt
+sudo tar -xf flutter_linux.tar.xz -C /opt
+
+# 添加 PATH
+export PATH="$PATH:/opt/flutter/bin"
+
+# 验证安装
+flutter doctor
+```
+
+### 2. 配置 Android SDK
+
+确保已安装 Android SDK 并设置 ANDROID_HOME 环境变量：
+
+```bash
+export ANDROID_HOME=/path/to/android-sdk
+export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin"
+export PATH="$PATH:$ANDROID_HOME/platform-tools"
+```
+
+### 3. 项目设置
+
+```bash
+# 进入项目目录
+cd flutter_openclaw_client
+
+# 获取依赖
+flutter pub get
+
+# 运行代码生成 (如果需要)
+dart run build_runner build --delete-conflicting-outputs
+```
+
+### 4. 构建 APK
+
+#### Debug 版本
+```bash
+flutter build apk --debug
+```
+
+#### Release 版本
+```bash
+flutter build apk --release
+```
+
+输出路径: `build/app/outputs/flutter-apk/app-release.apk`
+
+#### 指定 ABI
+```bash
+# 仅构建 arm64
+flutter build apk --release --target-platform android-arm64
+
+# 构建多个 ABI
+flutter build apk --release --target-platform android-arm,android-arm64,android-x64
+```
+
+### 5. 构建 App Bundle (Google Play)
+
+```bash
+flutter build appbundle --release
+```
+
+输出路径: `build/app/outputs/bundle/release/app-release.aab`
+
+## 项目结构
+
+```
+flutter_openclaw_client/
+├── android/          # Android 平台代码
+├── ios/             # iOS 平台代码
+├── lib/             # Dart 主代码
+├── linux/           # Linux 平台代码
+├── macos/           # macOS 平台代码
+├── packages/        # 本地依赖包
+├── test/            # 测试代码
+├── windows/         # Windows 平台代码
+├── pubspec.yaml     # 依赖配置
+└── build_apk.sh     # 构建脚本
+```
+
+## 签名配置
+
+项目已配置调试签名密钥：`android/app/debug.keystore`
+
+如需使用正式签名，修改 `android/key.properties`：
+
+```properties
+storeFile=/path/to/your/keystore.jks
+storePassword=your_store_password
+keyAlias=your_key_alias
+keyPassword=your_key_password
+```
+
+## 常见问题
+
+### Flutter 命令未找到
+确保已将 Flutter bin 目录添加到 PATH。
+
+### 构建失败 - 缺少依赖
+运行 `flutter pub get` 获取依赖。
+
+### 构建失败 - 代码生成问题
+运行 `dart run build_runner build --delete-conflicting-outputs`。
+
+### Android SDK 未找到
+运行 `flutter doctor` 检查环境配置。
+
+## 一键构建
+
+使用提供的构建脚本：
+
+```bash
+./build_apk.sh
+```
--- a/PROJECT_STRUCTURE.md
+++ b/PROJECT_STRUCTURE.md
@@ -0,0 +1,170 @@
+# ServerBox 项目结构说明
+
+## 项目概述
+- **名称**: ServerBox (flutter_openclaw_client)
+- **版本**: 1.0.1351+1351
+- **描述**: 跨平台服务器状态监控和 SSH 管理工具
+- **包名**: tech.lolli.toolbox
+
+## 技术栈
+- **框架**: Flutter 3.29+
+- **语言**: Dart 3.11+
+- **状态管理**: Riverpod
+- **本地存储**: Hive
+
+## 目录结构
+
+### lib/ - 主代码目录
+```
+lib/
+├── main.dart              # 应用入口
+├── app.dart               # 应用配置
+├── intro.dart             # 引导页面
+├── core/                  # 核心功能
+├── data/                  # 数据层
+│   ├── model/            # 数据模型
+│   ├── store/            # 状态存储
+│   └── res/              # 资源定义
+├── view/                  # 视图层
+│   ├── page/             # 页面
+│   │   ├── container/    # 容器管理
+│   │   ├── private_key/  # SSH 密钥管理
+│   │   ├── server/       # 服务器管理
+│   │   ├── setting/      # 设置
+│   │   ├── snippet/      # 代码片段
+│   │   └── storage/      # 存储管理
+│   └── widget/           # 公共组件
+├── generated/            # 生成的代码
+│   └── l10n/            # 本地化
+└── hive/                # Hive 适配器
+```
+
+### android/ - Android 平台配置
+```
+android/
+├── app/
+│   ├── build.gradle      # 应用构建配置
+│   ├── debug.keystore    # 调试签名密钥
+│   └── src/main/
+│       ├── AndroidManifest.xml
+│       ├── kotlin/tech/lolli/toolbox/
+│       │   ├── MainActivity.kt
+│       │   ├── ForegroundService.kt
+│       │   └── widget/
+│       │       ├── HomeWidget.kt
+│       │       └── WidgetConfigureActivity.kt
+│       └── res/          # 资源文件
+├── build.gradle          # 项目构建配置
+├── key.properties        # 签名配置
+├── local.properties      # 本地配置
+└── gradle.properties     # Gradle 配置
+```
+
+### packages/ - 本地包
+```
+packages/
+├── circle_chart/         # 圆形图表组件
+├── dartssh2/            # SSH2 客户端
+├── fl_build/            # 构建工具
+├── fl_lib/              # 公共库
+├── plain_notification_token/  # 通知令牌
+├── server_box_monitor/  # 服务器监控
+├── watch_connectivity/  # 手表连接
+└── xterm/               # 终端模拟器
+```
+
+## 构建配置
+
+### 签名配置 (android/key.properties)
+```
+storeFile=app/debug.keystore
+storePassword=android
+keyAlias=androiddebugkey
+keyPassword=android
+```
+
+### 版本信息
+- versionName: 1.0.1351
+- versionCode: 1351
+- minSdk: Flutter 默认
+- targetSdk: Flutter 默认
+
+## 主要功能模块
+
+1. **服务器管理**
+   - SSH 连接和终端
+   - SFTP 文件传输
+   - 服务器状态监控 (CPU, 内存, 磁盘, 网络)
+   - Docker 容器管理
+   - 进程管理
+
+2. **Snippet (代码片段)**
+   - 保存和快速执行常用命令
+
+3. **密钥管理**
+   - SSH 私钥管理
+
+4. **容器管理**
+   - Docker 容器操作
+
+5. **系统工具**
+   - 网络唤醒 (Wake-on-LAN)
+   - 端口转发
+
+## 平台支持
+- Android
+- iOS
+- macOS
+- Linux
+- Windows
+
+## 构建命令
+
+### 获取依赖
+```bash
+flutter pub get
+```
+
+### 构建 APK
+```bash
+flutter build apk --release
+```
+
+### 构建 App Bundle
+```bash
+flutter build appbundle --release
+```
+
+### 构建指定 ABI
+```bash
+flutter build apk --release --target-platform android-arm64
+```
+
+## 项目依赖
+
+### 主要依赖
+- flutter_riverpod: 状态管理
+- dio: 网络请求
+- dartssh2: SSH 连接
+- hive_ce_flutter: 本地存储
+- fl_chart: 图表
+- xterm: 终端模拟
+
+### 开发依赖
+- build_runner: 代码生成
+- freezed: 不可变类生成
+- json_serializable: JSON 序列化
+- riverpod_generator: Riverpod 代码生成
+
+## 注意事项
+
+1. 首次构建需要运行代码生成:
+   ```bash
+   dart run build_runner build
+   ```
+
+2. 本项目使用本地包，位于 packages/ 目录
+
+3. Android 构建需要配置签名密钥 (已配置 debug 密钥)
+
+4. 国际化文件已预生成，位于 lib/generated/l10n/
--- a/build_and_push.sh
+++ b/build_and_push.sh
@@ -0,0 +1,54 @@
+#!/bin/bash
+# 完整构建和上传脚本
+
+set -e
+
+echo "=== ServerBox 完整构建脚本 ==="
+
+# 配置环境
+export PATH="$PATH:/opt/flutter/bin"
+export ANDROID_HOME=/opt/android-sdk
+export ANDROID_SDK_ROOT=/opt/android-sdk
+
+cd /root/.openclaw/workspace/flutter_opencode_client
+
+echo "=== 步骤 1: 获取 Flutter 依赖 ==="
+flutter pub get
+
+echo "=== 步骤 2: 构建 Release APK ==="
+flutter build apk --release
+
+APK_PATH="build/app/outputs/flutter-apk/app-release.apk"
+if [ -f "$APK_PATH" ]; then
+    echo ""
+    echo "=== APK 构建成功! ==="
+    echo "APK 路径: $PWD/$APK_PATH"
+    ls -lh "$APK_PATH"
+    
+    # 复制 APK 到项目根目录
+    cp "$APK_PATH" ./app-release.apk
+    echo "APK 已复制到: $PWD/app-release.apk"
+else
+    echo ""
+    echo "=== APK 构建失败 ==="
+    exit 1
+fi
+
+echo ""
+echo "=== 步骤 3: 配置 Git 仓库 ==="
+git remote add opencode ssh://git@git.wqyblog.cn:2222/wuqiyang312/flutter_opencode_client.git 2>/dev/null || git remote set-url opencode ssh://git@git.wqyblog.cn:2222/wuqiyang312/flutter_opencode_client.git
+
+echo ""
+echo "=== 步骤 4: 提交更改 ==="
+git add -A
+git commit -m "Build: Release APK v1.0.1352 - $(date '+%Y-%m-%d %H:%M:%S')" || echo "Nothing to commit"
+
+echo ""
+echo "=== 步骤 5: 推送到远程仓库 ==="
+echo "推送到 opencode..."
+git push -u opencode main --force
+
+echo ""
+echo "=== 完成! ==="
+echo "APK 路径: $PWD/app-release.apk"
+echo "Git 仓库: ssh://git@git.wqyblog.cn:2222/wuqiyang312/flutter_opencode_client.git"
--- a/build_apk.sh
+++ b/build_apk.sh
@@ -0,0 +1,51 @@
+#!/bin/bash
+# ServerBox 构建脚本
+
+set -e
+
+PROJECT_DIR="$(cd "$(dirname "$0")" && pwd)"
+FLUTTER_BIN="/opt/flutter/bin/flutter"
+
+echo "=== ServerBox 构建脚本 ==="
+echo "项目目录: $PROJECT_DIR"
+echo ""
+
+# 检查 Flutter 是否可用
+if [ ! -f "$FLUTTER_BIN" ]; then
+    echo "错误: Flutter 未找到 at $FLUTTER_BIN"
+    echo "请先安装 Flutter SDK"
+    exit 1
+fi
+
+echo "Flutter 版本:"
+$FLUTTER_BIN --version
+echo ""
+
+# 进入项目目录
+cd "$PROJECT_DIR"
+
+# 获取依赖
+echo "=== 获取 Flutter 依赖 ==="
+$FLUTTER_BIN pub get
+
+# 运行代码生成 (如果需要)
+# echo "=== 运行代码生成 ==="
+# dart run build_runner build --delete-conflicting-outputs
+
+# 构建 APK
+echo "=== 构建 Release APK ==="
+$FLUTTER_BIN build apk --release
+
+# 检查构建结果
+APK_PATH="build/app/outputs/flutter-apk/app-release.apk"
+if [ -f "$APK_PATH" ]; then
+    echo ""
+    echo "=== 构建成功! ==="
+    echo "APK 路径: $PROJECT_DIR/$APK_PATH"
+    ls -lh "$APK_PATH"
+else
+    echo ""
+    echo "=== 构建失败 ==="
+    echo "未找到 APK 文件"
+    exit 1
+fi
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
 name: server_box
 description: server status & toolbox app.
 publish_to: "none"
-version: 1.0.1351+1351
+version: 1.0.1352+1352

 environment:
  sdk: ">=3.11.0"