# wails3-vue3-autoshell

**Repository Path**: TheFreeOne/wails3-vue3-autoshell

## Basic Information

- **Project Name**: wails3-vue3-autoshell
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-31
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# run-custom-script

基于 SSH 的服务器自动脚本工具：把文件上传到服务器工作目录，再按步骤完成重命名 / 移动 / 复制。

技术栈：**Wails3 + Vue3 + TypeScript + TDesign Vue Next + Vite**。

## 原始需求

- [x] 使用 tdesign-vue-next + vue3 + wails3 + vite8 构建项目
- [x] 支持添加服务器
  - [x] 支持根据账号加密码
  - [x] 支持私钥连接
- [x] 支持根据服务器添加自动脚本
  - [x] 添加脚本需要先设置工作目录
  - [x] 运行脚本前支持选择文件或者文件夹
- [x] 脚本是按照步骤来的，步骤支持重命名，移动文件，复制文件的操作

## 环境要求

- Go 1.26+
- Node.js 20+
- Wails3 CLI：

```bash
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
```

## 常用命令

```bash
wails3 dev        # 开发模式（前端热更新）
wails3 build      # 构建可执行文件 -> bin/run-custom-script
wails3 package    # 打包 macOS .app -> bin/run-custom-script.app（等同 package:release）
```

### 两个打包命令

| 命令 | 说明 | 产物 |
| --- | --- | --- |
| `wails3 task package:release` | 正式包，**不启用** WebView 开发者工具 | `bin/run-custom-script.app` |
| `wails3 task package:debug` | 调试包，**启用** WebView 开发者工具，启动 1 秒后自动打开 | `bin/debug/run-custom-script.app` |

- 两者都带 `production` 构建标签（保留裁剪与 strip），调试包只额外加了 `devtools` 标签，因此可同时保留两份产物。
- 调试包里可以随时用 `Cmd + Option + I` 打开/关闭开发者工具，也能右键页面选择「检查元素」。
- 控制器：`devtools_on.go` / `devtools_off.go` 中的 `devToolsEnabled` 常量由 `devtools` 构建标签切换，窗口通过 `DevToolsEnabled` 选项和 `OpenDevTools()` 打开。

前端可单独调试：`cd frontend && npm run dev`（此时无法调用后端方法）。

## 使用流程

1. **服务器**：添加主机地址、端口、用户名，选择「账号密码」或「私钥文件」认证，保存后可点「测试连接」验证。
2. **自动脚本**：新建脚本时必须先填写服务器上的**工作目录**（绝对路径，例如 `/opt/app`）。
3. **执行步骤**：每步选择「重命名 / 移动 / 复制」，填写源与目标路径。
   - 路径填写相对路径时基于工作目录，例如 `release/app.zip`；
   - 也可以填写绝对路径；
   - `{name}` 表示运行前选中的文件 / 文件夹名称，`{workdir}` 表示工作目录；
   - 源留空时默认使用 `{name}`。
4. **运行**：点击「运行脚本」，可选一个本地文件或文件夹，会先通过 SFTP 上传到工作目录，然后依次执行步骤，日志实时显示在面板中。
5. 数据保存在 `~/Library/Application Support/run-custom-script/data.db`（SQLite，macOS），侧边栏底部会显示实际路径。

## 项目结构

```
.
├── main.go                 # 应用入口：创建 Wails 应用、注册服务与事件、嵌入前端产物
├── service.go              # AppService：暴露给前端的后端 API（服务器/脚本 CRUD、运行与取消）
├── mode_dev.go             # 构建标签 !production：开发构建标记 isDevBuild = true
├── mode_prod.go            # 构建标签 production：正式构建标记 isDevBuild = false
├── devtools_on.go          # 构建标签 devtools：调试包启用 WebView 开发者工具
├── devtools_off.go         # 构建标签 !devtools：正式包关闭开发者工具
├── Taskfile.yml            # go-task 任务总入口：build / package / run / dev / 双模式打包
├── dev.sh / dev.cmd        # 一键启动开发模式（macOS/Linux 与 Windows）
├── package-release.sh/.cmd # 一键打包正式版（不带开发者工具）
├── package-debug.sh/.cmd   # 一键打包调试版（带开发者工具）
├── go.mod / go.sum         # Go 模块依赖声明
├── internal/               # Go 后端内部实现（不对外暴露）
│   ├── model/              #   数据模型：Server / Script / Step / RemoteEntry / ServerView
│   ├── remote/             #   SSH + SFTP 远程能力
│   │   ├── client.go       #     连接封装（Dial、认证、远程命令执行、路径解析）
│   │   ├── ops.go          #     文件操作（复制/移动/上传、{name}/{timestamp} 等变量替换）
│   │   └── runner.go       #     脚本执行引擎：依次执行步骤并回传日志
│   └── store/              #   本地持久化
│       ├── store.go        #     SQLite 存储（服务器表 + 脚本表），旧 data.json 自动迁移
│       └── credentials.go  #     系统钥匙串封装（密码/私钥口令不落盘）
├── frontend/               # Vue3 + TypeScript + Vite 前端
│   ├── bindings/           #   wails3 自动生成的 Go → TS 绑定（勿手动修改）
│   ├── src/                #   前端源码
│   │   ├── App.vue         #     根组件：侧边栏 + 路由视图切换
│   │   ├── views/          #     ServersView（服务器管理）、ScriptsView（脚本编辑）
│   │   ├── components/     #     RunPanel.vue（运行面板：选文件、实时日志、取消）
│   │   ├── utils/          #     stepPreview.ts（步骤路径预览，与 Go 侧变量逻辑一致）
│   │   └── state.ts        #     全局响应式状态与数据加载函数
│   └── dist/               #   前端构建产物，被 main.go 以 embed 方式打包进二进制
├── build/                  # Wails3 各平台构建配置与任务
│   ├── config.yml          #   打包元信息（应用名、图标、identifier 等）
│   ├── appicon.png         #   应用图标源图（生成各平台图标）
│   ├── Taskfile.yml        #   跨平台通用构建任务
│   └── darwin|windows|linux|ios|android/  # 各平台专属任务与资源（Info.plist、NSIS 等）
├── bin/                    # 构建产物目录（gitignore）
│   ├── run-custom-script           #   wails3 build 生成的可执行文件
│   ├── run-custom-script.app       #   正式版 .app（package:release）
│   └── debug/run-custom-script.app #   调试版 .app（package:debug）
└── .task/                  # go-task 校验缓存（gitignore）
```

### 根目录 Go 文件

- `main.go`：应用入口。初始化 SQLite 存储，创建 Wails 应用并注册 `AppService`，通过 `//go:embed all:frontend/dist` 嵌入前端静态资源；调试包会在启动 1 秒后自动打开开发者工具。
- `service.go`：唯一的后端服务层。向前端提供服务器与脚本的增删改查、连通性测试、文件选择对话框，以及异步执行脚本（日志经 `run:log` / `run:done` 事件推送到前端）。
- `mode_dev.go` / `mode_prod.go`：由 `production` 构建标签切换 `isDevBuild` 常量，控制开发构建是否启用 DevTools。
- `devtools_on.go` / `devtools_off.go`：由 `devtools` 构建标签切换 `devToolsEnabled` 常量，控制打包出的 `.app` 是否内置 WebView 开发者工具。

### `internal/` 后端模块

- `model`：共享数据结构。`Server`（连接信息）、`Script`（工作目录 + 步骤列表）、`Step`（rename / move / copy / sh 四类步骤）、`ServerView`（返回前端时隐藏密码等敏感字段）。
- `remote`：远程操作核心。`client.go` 负责 SSH/SFTP 建连与密码/私钥两种认证；`ops.go` 实现递归复制、移动（跨分区退化为复制+删除）、上传及路径占位符展开；`runner.go` 是执行引擎，连接后先上传所选文件，再按步骤顺序执行并逐行回传日志，支持取消与「仅当源存在时执行」。
- `store`：持久化层。`store.go` 用 SQLite（modernc 纯 Go 驱动，免 CGO）保存非敏感数据，并自动迁移旧版 `data.json`；`credentials.go` 通过 `go-keyring` 把密码/私钥口令写入系统钥匙串，单测时用内存实现替代。

### `frontend/` 前端

- `bindings/`：`wails3 generate bindings` 自动生成，前端借此直接调用 Go 方法（如 `AppService.SaveServer`）及监听后端事件，请勿手动编辑。
- `src/views/ServersView.vue`：服务器管理页（添加、编辑、测试连接、认证方式选择）。
- `src/views/ScriptsView.vue`：脚本编辑页（工作目录设置、步骤卡片增删排序、路径预览）。
- `src/components/RunPanel.vue`：运行面板（选择本地文件上传、实时日志展示、取消执行）。
- `src/utils/stepPreview.ts`：在前端还原 Go 侧的路径变量替换逻辑，用于步骤保存前的效果预览。
- `src/state.ts`：基于 `reactive` 的全局状态（当前 Tab、服务器/脚本列表、运行状态与日志）。

### `build/` 与脚本

- `Taskfile.yml`（根）：任务入口，按 `GOOS` 分发到 `build/<平台>/Taskfile.yml`；定义 `package:release`（产物 `bin/run-custom-script.app`）与 `package:debug`（附加 `devtools` 标签、产物 `bin/debug/run-custom-script.app`）。
- `build/config.yml`：打包元信息（应用名称、图标、macOS bundle identifier 等）。
- `dev.sh` / `package-release.sh` / `package-debug.sh`（及对应 `.cmd`）：独立一键脚本，自动检查 wails3 安装与端口占用，无需记忆 task 命令。

## 行为说明

- 同一时间只允许运行一个脚本，运行中可以取消。
- 复制 / 移动时如果目标已存在会中止该步骤，避免误覆盖。
- 移动（含重命名）优先使用 SFTP rename，跨分区失败时自动退化为「复制后删除源」。
- 目录复制与上传均为递归操作。

## 安全提示

- 密码和私钥口令**不再落盘到数据文件**，而是存入系统钥匙串（macOS Keychain / Windows Credential Manager / Linux Secret Service），由 `go-keyring` 统一封装。
- SQLite 数据库 `data.db` 只保存服务器地址、用户名、脚本步骤等非敏感信息；单元测试会校验数据库文件中不出现明文密码。
- 旧版本的 `data.json` 会在首次启动时自动导入数据库（密码一并写入钥匙串），随后重命名为 `data.json.bak` 保留备份。
- 运行脚本时从钥匙串读取凭据；如果钥匙串访问被拒绝，界面上会提示「读取系统钥匙串失败」。
- SSH 连接未做 known_hosts 校验（首次连接自动信任），如需严格校验可修改 `internal/remote/client.go` 中的 `HostKeyCallback`。