TypePHP 编译器
https://swoole.com/aot/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
107 lines
4.3 KiB
107 lines
4.3 KiB
# TypePHP SSH Tunnel Manager（Qt）
|
|
|
|
这是一个 TypePHP 桌面应用示例。Qt/C++ 只承担窗口、控件、UI 事件队列和
|
|
`QProcess` 桥接；规则校验、CRUD、JSON 持久化、SSH 参数生成、自动启动和运行
|
|
状态均由 TypePHP 实现。
|
|
|
|
## 功能
|
|
|
|
- 本地转发：把服务器可访问的目标端口映射到本地监听端口（OpenSSH `-L`）。
|
|
- 远程转发：把本地可访问的目标端口映射到服务器监听端口（OpenSSH `-R`）。
|
|
- SOCKS5：通过 SSH 服务器建立本地 SOCKS5 代理（OpenSSH `-D`）。
|
|
- 新建、查看、编辑和删除规则。
|
|
- 单条隧道启动、停止、状态展示和 SSH 输出日志。
|
|
- 支持中文输入法组合事件（Linux IBus/Fcitx、Windows TSF/IMM）。
|
|
- 表格列宽可拖动调整，刷新规则时不会重置列宽。
|
|
- 映射端点分别显示为“本机地址”和“远程地址”；远程转发会按实际方向交换显示。
|
|
- 状态列使用状态灯：运行中为绿色，已停止或错误为红色，过渡状态为橙色。
|
|
- 日志按隧道独立保存在内存中，选择表格行时只显示该隧道最近 500 条日志；当前日志增量追加，切换隧道时才进行一次有限量重绘。
|
|
- 可清理当前选中隧道的日志，不影响其他隧道或正在运行的 SSH 进程。
|
|
- SOCKS5 连接失败日志会显示请求的域名或 IP 及端口，并过滤用于关联目标的 OpenSSH 调试输出。
|
|
- 新建、编辑规则时可勾选“调试”，为该隧道输出完整的 OpenSSH DEBUG2 日志；该选项随规则持久化。
|
|
- 启动/停止按钮随所选隧道状态联动，禁止重复启动或停止。
|
|
- 可选私钥和 SSH 自定义端口。
|
|
- 启动时检查全部持久化规则，未运行的隧道会自动启动。
|
|
- JSON 配置原子写入、`fsync` 和双份备份，主配置损坏时自动恢复。
|
|
- 使用 `QProcess(program, arguments)`，不经过 shell。
|
|
- 应用图标内嵌到程序中，支持 Linux、macOS 和 Windows 多 DPI 显示；Windows
|
|
可执行文件同时携带 PE 图标资源。
|
|
|
|
## 分层
|
|
|
|
```text
|
|
main.php / app/
|
|
TypePHP：业务规则、CRUD、持久化、SSH argv、状态机
|
|
│
|
|
php-src/qt_tunnel.stub.php
|
|
原生函数声明
|
|
│
|
|
cpp-src/qt_tunnel.cc
|
|
Qt Widgets、对话框、事件队列、QProcess
|
|
```
|
|
|
|
C++ 层不会拼接 SSH 命令，也不会读写配置文件。对话框提交的数据以事件返回给
|
|
TypePHP，经过验证后才会写入仓库。
|
|
|
|
## 依赖
|
|
|
|
- TypePHP 编译器及其 PHP 8.4/Phpx 构建环境
|
|
- Qt 6 Widgets 开发包
|
|
- OpenSSH 客户端（运行时需要 `ssh` 位于 `PATH`）
|
|
|
|
Ubuntu/Debian：
|
|
|
|
```bash
|
|
sudo apt install qt6-base-dev openssh-client
|
|
```
|
|
|
|
## 构建
|
|
|
|
项目默认使用 Debian/Ubuntu 的 Qt 6 系统路径：
|
|
|
|
```bash
|
|
php ../../bin/tpc.php project.yml --debug -o ssh_tunnel_manager
|
|
./ssh_tunnel_manager
|
|
```
|
|
|
|
Qt 安装在其他目录时，运行下面的命令获取参数，并相应调整 `project.yml`：
|
|
|
|
```bash
|
|
pkg-config --cflags --libs Qt6Widgets
|
|
```
|
|
|
|
Windows 使用 Qt 6 MSVC SDK 时，将 `cxx-flags` 改为 Qt 的 `include`、
|
|
`include/QtCore`、`include/QtGui`、`include/QtWidgets`，将 `ld-flags` 改为
|
|
`Qt6Widgets.lib`、`Qt6Gui.lib`、`Qt6Core.lib`。部署时执行：
|
|
|
|
```powershell
|
|
windeployqt ssh_tunnel_manager.exe
|
|
```
|
|
|
|
Windows 10/11 可在“可选功能”中安装 OpenSSH Client。
|
|
|
|
## 配置文件
|
|
|
|
- Linux/macOS：`$XDG_CONFIG_HOME/typephp/ssh-tunnel-manager.json`，未设置时使用
|
|
`~/.config/typephp/ssh-tunnel-manager.json`
|
|
- Windows：`%APPDATA%\TypePHP\ssh-tunnel-manager.json`
|
|
- 测试或便携运行：通过 `TYPEPHP_SSH_TUNNEL_CONFIG` 指定完整路径
|
|
|
|
同目录下的 `.bak` 文件是完整镜像备份。读取主配置失败时，应用会验证备份并
|
|
自动恢复主文件。所有成功保存的规则都会在下一次启动时自动建立，不再提供
|
|
容易造成遗漏的单条“自动启动”开关。
|
|
|
|
配置中不保存密码。推荐使用 SSH 私钥和 `ssh-agent`；应用为避免弹出不可见的
|
|
终端密码提示，固定启用 `BatchMode=yes`。
|
|
|
|
远程转发是否能监听非回环地址由服务器的 `sshd_config` 中 `GatewayPorts`
|
|
设置决定；本工具不会绕过服务器安全策略。
|
|
|
|
## 业务层测试
|
|
|
|
该测试不依赖 Qt，可以直接用 PHP 执行：
|
|
|
|
```bash
|
|
php tests/domain_test.php
|
|
php tests/startup_test.php
|
|
```
|
|
|