# voltiusLocal

**Repository Path**: web/voltius-local

## Basic Information

- **Project Name**: voltiusLocal
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Voltius-Local

> 一款现代化的多主机管理工具，支持 SSH 终端、SFTP 文件传输、端口转发、Docker 管理等功能。
> 本分支为 **纯本地账户版**，已移除 Cloud Account 功能，专注于本地使用场景。

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](./LICENSE)
[![Version](https://img.shields.io/badge/version-0.39.2-green.svg)](./package.json)
[![Tauri](https://img.shields.io/badge/Tauri-2.x-orange.svg)](https://tauri.app/)
[![React](https://img.shields.io/badge/React-19-blue.svg)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6.svg)](https://www.typescriptlang.org/)
[![Rust](https://img.shields.io/badge/Rust-1.x-dea584.svg)](https://www.rust-lang.org/)

---

## ✨ 特性

### 核心功能
- 🖥️ **SSH 终端** - 内置 xterm.js，支持多标签页、分屏、会话持久化
- 📂 **SFTP 文件管理** - 双面板文件浏览、上传下载、远程编辑
- 🔌 **端口转发** - 本地/远程端口转发，UI 化隧道管理
- 🐳 **Docker 集成** - 容器、镜像、卷、网络管理
- 🌐 **Proxmox 集成** - 虚拟机/容器管理

### 账户与安全
- 🔐 **本地账户** - 无密码账户（自动生成密钥）或设置主密码
- 🔒 **保险库锁定** - 会话锁定/解锁，自动锁定超时
- 🔑 **密钥管理** - 内置 SSH 密钥生成、导入、管理
- 💾 **本地加密存储** - 凭证加密存储于系统密钥链

### 跨平台
- 🪟 Windows
- 🐧 Linux  
- 🍎 macOS
- 📱 Android

### 其他
- 🎨 现代化 UI（玻璃拟态设计语言）
- 🌍 多语言支持
- 🔌 插件系统
- 📋 命令面板（快速搜索/操作）

---

## 📦 系统要求

### 桌面端
| 依赖 | 版本要求 | 说明 |
|------|---------|------|
| Node.js | ≥ 18 | 推荐 20 LTS |
| pnpm | ≥ 11 | 项目指定包管理器 |
| Rust | ≥ 1.70 | Tauri 后端 |
| Git | ≥ 2.30 | 可选，用于克隆 |

### Android 构建（可选）
| 依赖 | 说明 |
|------|------|
| Android SDK | compileSdk 34+ |
| Android NDK | r25+ |
| Rust targets | aarch64-linux-android, armv7-linux-androideabi, x86_64-linux-android, i686-linux-android |
| JDK | 17+ |

---

## 🚀 快速开始

### 1. 克隆仓库

```bash
git clone https://gitee.com/web/voltius-local.git
cd voltius-local
```

### 2. 安装依赖

```bash
pnpm install
```

### 3. 开发模式运行

```bash
pnpm tauri dev
```

这会同时启动前端 Vite 开发服务器和 Tauri 原生窗口。

### 4. 构建生产版本

```bash
# 前端构建
pnpm build

# Tauri 打包
pnpm tauri build
```

构建产物位于 `src-tauri/target/release/bundle/` 目录。

---

## 📱 Android 构建

> 详细 Android 开发工作流请参阅 [docs/android-dev.md](./docs/android-dev.md)

### 使用 Docker 构建（推荐）

```bash
# 构建 aarch64 APK（真机）
docker build -t voltius-android -f Dockerfile.android .
docker run --rm -v $PWD:/project voltius-android bash -c \
  "cd /project && src-tauri/gen/android/gradlew :app:assembleDebug"

# 输出路径
# src-tauri/gen/android/app/build/outputs/apk/debug/app-debug.apk
```

### 本地构建

```bash
# 确保已安装 Android SDK/NDK 并设置环境变量
$env:ANDROID_HOME = "C:\Users\<你>\AppData\Local\Android\Sdk"
$env:ANDROID_NDK_HOME = "$env:ANDROID_HOME\ndk\<version>"

# 添加 Rust Android targets（全平台需要 4 个）
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
```

### 全平台 Release 打包

`tauri android build` 默认就是 **release 模式 + 全架构**（arm64-v8a / armeabi-v7a / x86 / x86_64），无需额外参数。

```powershell
# 全平台 APK（4 个架构一起打包，体积最大，适合分发）
pnpm tauri android build --apk

# 全平台 AAB（Google Play 商店推荐格式）
pnpm tauri android build --aab

# 按架构拆分 APK（推荐，体积小，按需安装）
pnpm tauri android build --apk --split-per-abi

# 指定单架构（如只为自己 arm64 手机打）
pnpm tauri android build --apk --target aarch64
```

**产物路径**：

```
src-tauri/gen/android/app/build/outputs/
├── apk/
│   ├── arm64/release/app-arm64-release.apk      ← arm64 真机（推荐）
│   ├── arm/release/app-arm-release.apk          ← 旧手机 armeabi-v7a
│   ├── x86_64/release/app-x86_64-release.apk    ← 模拟器
│   ├── x86/release/app-x86-release.apk          ← 模拟器
│   └── universal/release/app-universal-release.apk  ← 全架构合一（体积最大）
└── aab/release/app-release.aab                  ← Google Play 上传格式
```

### R8 / ProGuard 注意事项（Release 必看）

Release 构建开启了 R8 代码压缩和混淆（`isMinifyEnabled = true`），以下规则缺一不可，否则会出现 **App 卡在启动画面**、**闪退** 或 **加密存储报错**：

| 规则文件 | 位置 | 作用 |
|---------|------|------|
| `proguard-rules.pro` | `src-tauri/gen/android/app/` | gen 目录下，Gradle 直接加载 |
| `proguard-voltius.pro` | `src-tauri/android/app/` | **覆盖层目录**，即使 gen 被 `tauri android init` reset 也不会丢 |

三条核心 keep 规则（见 `proguard-voltius.pro`）：

```proguard
# JNI 桥接类 — Rust 端通过类名字符串反射调用，R8 混淆后会找不到类
-keep class com.voltius.app.VoltiusKeychain { *; }
-keep class com.voltius.app.VoltiusDownloads { *; }
-keep class com.voltius.app.TerminalKeyboard { *; }
-keep class com.voltius.app.MainActivity { *; }
```

另外，`androidx.security:security-crypto`（EncryptedSharedPreferences）依赖 Google Tink，在 targetSdk 33+ 上会报 `javax.annotation.Nullable not found`，需加：

```proguard
-dontwarn javax.annotation.Nullable
-dontwarn javax.annotation.concurrent.GuardedBy
```

> 如果 release 构建后 App 卡死在 "Starting Voltius..."，**99% 是 JNI keep 规则丢了**。debug 构建不混淆所以一切正常。

### 覆盖层目录说明

`src-tauri/android/` 是 Tauri 的配置覆盖层，`tauri android init` 重新生成 `gen/android/` 时**不会删除**这个目录。建议把以下自定义文件放在覆盖层里：

```
src-tauri/android/
├── app/
│   ├── proguard-voltius.pro    ← 自定义 ProGuard 规则（已配置）
│   └── src/main/AndroidManifest.xml  ← 自定义 Manifest 权限（已配置）
```

`gen/android/app/build.gradle.kts` 的 `proguardFiles` 已同时扫描覆盖层目录，确保两边规则都会被加载。

### 精简 APK/AAB 体积（推荐，不影响功能）

默认就是 release 构建，只需指定单架构 + strip 符号即可大幅缩小体积：

```powershell
# PowerShell：单架构、去掉调试符号（适合大多数 arm64 设备）
$env:RUSTFLAGS = "-C strip=symbols"
$env:CARGO_PROFILE_RELEASE_STRIP = "symbols"
pnpm tauri android build --target aarch64 --aab

# 若需要 APK，可替换为：
# pnpm tauri android build --target aarch64 --apk

# 对比：debug 构建（体积大，仅用于开发调试）
pnpm tauri android build --debug --target aarch64 --apk
```

- 默认 release 比 `--debug` 小很多，无需额外加 `--release`
- `--target aarch64`：只构建当前设备 ABI，避免多架构包体积膨胀
- `--aab`：Android 商店更推荐的分发格式
- `strip=symbols`：去掉调试符号，通常不会影响运行功能

> 若只是给自己的手机安装测试，优先使用 `--target aarch64 --apk`。若面向商店分发，优先使用 `--target aarch64 --aab`。

### 安装到设备

```bash
# Release 构建产物（推荐）
adb install -r src-tauri/gen/android/app/build/outputs/apk/arm64/release/app-arm64-release.apk

# Debug 构建产物
adb install -r src-tauri/gen/android/app/build/outputs/apk/debug/app-debug.apk

# 启动
adb shell am start -n com.voltius.app/.MainActivity
```

---

## 🛠️ 常用命令

| 命令 | 说明 |
|------|------|
| `pnpm dev` | 启动 Vite 前端开发服务器 |
| `pnpm tauri dev` | 启动 Tauri 开发模式（含原生窗口） |
| `pnpm build` | 前端生产构建 |
| `pnpm tauri build` | 完整打包（桌面端安装包） |
| `pnpm test` | 运行单元测试 |
| `pnpm tsc` | TypeScript 类型检查 |
| `pnpm tauri android dev` | Android 开发模式 |
| `pnpm tauri android build` | Android APK/AAB 构建 |

---

## 📂 项目结构

```
voltius-local/
├── src/                     # 前端源代码（React + TypeScript）
│   ├── components/          # UI 组件
│   ├── services/            # 业务服务层
│   ├── stores/              # Zustand 状态管理
│   ├── utils/               # 工具函数
│   ├── i18n/                # 国际化资源
│   └── styles/              # 全局样式
├── src-tauri/               # Tauri 后端（Rust）
│   ├── src/
│   │   ├── commands/        # Tauri commands（前端可调用）
│   │   ├── local/           # 本地终端功能
│   │   ├── serial/          # 串口功能
│   │   ├── docker/          # Docker 集成
│   │   └── ...
│   ├── tauri.conf.json     # Tauri 配置
│   └── Cargo.toml           # Rust 依赖
├── crates/                  # 共享 Rust crate
│   ├── voltius-crypto/      # 加密原语
│   ├── voltius-crypto-wasm/ # WASM 版本加密
│   └── voltius-diagnostics/ # 诊断工具
├── scripts/                 # 构建/工具脚本
├── docs/                    # 文档
│   ├── local-only-account-plan.md   # 本地账户架构方案
│   ├── android-dev.md               # Android 开发工作流
│   ├── android-feature-gaps.md      # Android 功能兼容性
│   └── design-surfaces.md           # UI 设计规范
├── Dockerfile.android       # Android 构建镜像
├── package.json
├── Cargo.toml
└── LICENSE
```

---

## 🏗️ 账户架构

本项目移除了 Cloud Account 功能，仅保留以下两种本地账户模式：

| 模式 | 说明 |
|------|------|
| `local-nopassword` | 无密码账户，自动生成 32 字节随机密钥，适合个人单设备使用 |
| `local` | 用户设置主密码的账户，密码通过 Argon2 派生密钥，支持保险库锁定 |

### 已移除的 Cloud 功能
- ❌ Cloud Account 注册/登录
- ❌ 云端同步（`push`/`pull`/realtime sync）
- ❌ 团队/成员管理
- ❌ 订阅/Pro 功能
- ❌ 多 vault Pro 限制

> 详细修改方案见 [docs/local-only-account-plan.md](./docs/local-only-account-plan.md)

---

## 📝 开发说明

### 代码风格
- 前端：React 19 + TypeScript + TailwindCSS 4
- 后端：Rust
- 包管理：pnpm workspace
- 状态管理：Zustand
- 终端：xterm.js
- 构建工具：Vite 8 + Tauri 2

### 设计系统
Voltius 采用统一的 **Surface 设计语言**，通过核心 token（ring、elevation、radius）保持视觉一致性：
- `--t-ring` / `--t-ring-strong` - 边缘描边
- `--t-elev-1/2/3` - 阴影层级
- `--r-sm/md/lg` - 圆角层级

详见 [docs/design-surfaces.md](./docs/design-surfaces.md)

### 注意事项
1. **Android TLS** - Android 上需要使用预配置的 rustls TLS 客户端（见 `src-tauri/src/commands/http.rs::client_builder()`）
2. **类型检查** - 提交前确保 `tsc --noEmit` 无错误
3. **签名密钥** - `src-tauri/signing.key` 为私有签名密钥，禁止提交到版本库
4. **最小修改原则** - 优先修改现有文件而非创建新文件

---

## 🔌 插件配置地址

在 Voltius 应用内添加以下插件配置源以安装社区插件：

```
https://gitee.com/web/voltius_sync_config/releases/download/main/plugins.json
```

---

## 🔗 相关资源

- [Voltius 官网](https://voltius.app/)
- [Tauri 文档](https://tauri.app/v2/start/)
- [React 文档](https://react.dev/)
- [Rust 文档](https://www.rust-lang.org/learn)

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

## 📄 许可证

本项目基于 [GNU Affero General Public License v3.0](./LICENSE) 开源。

---

## 📦 第三方资源

- **Twemoji Country Flags** - CC BY 4.0（见 [NOTICE.md](./NOTICE.md)）
- **Nerd Font Symbols** - MIT License（见 [NOTICE.md](./NOTICE.md)）