# ssh-bradge

**Repository Path**: yanggan2021/ssh-bradge

## Basic Information

- **Project Name**: ssh-bradge
- **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-04-27
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ssh-brigde

这是一个将 SSH 会话桥接到串口（serial）的轻量级工具集合，包含：

- `ssh_bridge.py`：单一板卡的 SSH→串口 桥接，可同时开启一个用于读取内存日志的 HTTP 接口。
- `ssh_manager.py`：管理程序，基于 `config.ini` 启动多个桥接实例，并提供统一的 HTTP 管理接口。
- `config.ini`：配置示例与各板卡段（section）。
- `ssh-bridge.service`：systemd 服务模板（可调整 `User` 与 `WorkingDirectory`）。
- `keys/ssh_host_rsa_key`：SSH 主机密钥（若不存在，程序会自动生成）。
- `logs/`：磁盘日志目录（按板卡名与日期保存）。

## 功能概览

- 将远程 SSH 客户端的输入输出转发到本地串口设备（例如 `/dev/ttyUSB0`）。
- 支持交互式 shell 与 exec（一次性命令）两种模式。
- 内存中维护可滚动日志缓冲区，并可通过 HTTP 接口读取全部或尾部日志。
- 可将日志同步写入磁盘（`logs/{board_name}_YYYYMMDD.log`）。

## 环境与依赖

- Python 3.8+
- 依赖包：`paramiko`、`pyserial`

安装依赖：

```bash
pip3 install --user paramiko pyserial
```

（也可使用虚拟环境或系统包管理器）

## 快速使用示例

1) 单个桥接（手动运行）

```bash
python3 ssh_bridge.py -p 2201 -s /dev/ttyUSB0 -b 115200 -u root -pw Ncti2023 -n tl3588_A
```

- 如果未显式指定 `--http-port`，默认会使用 `ssh_port + 10000` 作为桥接的 HTTP 日志端口（例如 SSH 2201 → HTTP 12201）。

2) 使用管理器启动多个桥接（推荐在服务器上运行）

```bash
python3 ssh_manager.py -c config.ini --http-port 18081
```

- 管理器会读取 `config.ini` 中定义的每个板卡段并分别启动桥接，管理器提供统一的 HTTP 接口（默认端口可在 `default.http_port` 中配置）。

3) 通过 systemd 运行（示例）

```bash
sudo cp ssh-bridge.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now ssh-bridge.service
```

编辑 `ssh-bridge.service`，确保 `User` 与 `WorkingDirectory` 与实际系统环境匹配。

## 配置说明（config.ini）

示例片段：

```ini
[default]
username = root
password = Ncti2023
buffer_size = 1048576
log_enabled = true
log_dir = /home/yanggan/ssh-brigde/logs
http_port = 18081

[tl3588_B]
port = 2202
serial_device = /dev/ttyUSB1
baudrate = 115200
```

- 每个非 `default` 的段名即为板卡名称（`board_name`）。
- 启动时可通过 `--section` 指定要使用的段，或者让 `ssh_bridge.py` 自动选择唯一段或 `TEST_BOARD`。

## HTTP 接口说明

下面把桥接实例和管理器的 HTTP 操作放在一张表里，便于查阅。

| 适用对象 | 方法 | 路径 | 参数 | 功能 |
| --- | --- | --- | --- | --- |
| 桥接实例 | GET | `/`、`/health` | 无 | 返回当前桥接状态：`board_name`、`serial_device`、`ssh_port`、`http_port`、`buffer_size`、`log_enabled`、`log_bytes` 等。 |
| 桥接实例 | GET | `/log` | `n` / `chars` / `count` / `tail` | 返回全部内存日志；带参数时返回尾部指定字节数。 |
| 桥接实例 | GET | `/tail`、`/last` | `n` / `chars` / `count` / `tail` | 返回最后 N 字节，默认 4096。 |
| 桥接实例 | GET | `/size` | 无 | 返回缓冲区字节长度（`text/plain`）。 |
| 桥接实例 | POST | `/log/clear` | 无 | 清空内存日志并截断磁盘日志。 |
| 管理器 | GET | `/`、`/health`、`/status` | `board`（兼容 `name`） | 返回所有桥接状态；多桥接场景下可按板卡名查询单板状态。 |
| 管理器 | GET | `/operations` | 无 | 返回支持的 HTTP 操作列表。 |
| 管理器 | GET | `/log` | `board`、`lines`、`chars`（兼容 `n` / `count` / `tail`） | 返回指定板卡日志；不带 `lines` 时返回全部日志，`lines` 与 `chars` 不能同时使用。 |
| 管理器 | POST | `/log/clear` | `board`（兼容 `name`） | 清空指定板卡的内存日志与磁盘日志。 |
| 管理器 | POST | `/command` | `board`（兼容 `name`）、`command`（兼容 `cmd`） | 异步发送串口命令，HTTP 请求立即返回。 |

端口规则：

- 桥接实例默认监听端口由代码自动推导为 `http_port = ssh_port + 10000`，因此当 SSH 端口是 `2201` 时，默认 HTTP 端口就是 `12201`。如果显式指定 `--http-port`，则以该值为准。
- 管理器使用共享 HTTP 端口，优先读取命令行参数 `--http-port`，否则读取 `default.http_port`，示例为 `18081`。

示例：

```bash
# 桥接实例示例（单独启动 ssh_bridge.py 后可访问；SSH 2201 -> HTTP 12201）
curl http://localhost:12201/health
curl http://localhost:12201/log?chars=200
curl -X POST http://localhost:12201/log/clear

# 管理器示例：共享 HTTP 18081
curl http://localhost:18081/status
curl "http://localhost:18081/log?board=tl3588_B&lines=50"
curl "http://localhost:18081/log?board=tl3588_B&chars=200"
curl -X POST http://localhost:18081/log/clear -d "board=tl3588_B"
curl -X POST -d "board=tl3588_B&command=uname -a" http://localhost:18081/command
# 或 JSON
curl -X POST -H "Content-Type: application/json" -d '{"board":"tl3588_B","command":"uptime"}' http://localhost:18081/command
```

说明：`lines=N` 返回的是尾部 N 行，不是前 N 行。为了便于 `wc -l` 统计，服务会补齐最终换行符，因此如果你执行 `curl ... | wc -l`，结果会更贴近实际行数。

## SSH 连接示例

- 交互式 shell：

```bash
ssh -p 2202 root@<host>
```

- Exec 模式（一次性命令）：

```bash
ssh -p 2202 root@<host> 'ls -la'
```

（用户名/密码以 `config.ini` 或命令行参数为准）

## 日志

- 内存缓冲区以循环方式保存最近 `buffer_size` 字节；可通过 HTTP 获取全部或尾部日志。
- 如果启用磁盘日志（`log_enabled = true`），文件保存目录为 `log_dir`，文件名格式：`{board_name}_YYYYMMDD.log`。

查看磁盘日志示例：

```bash
ls logs/
tail -f logs/tl3588_B_20260508.log
```

## 常见问题与排查建议

- 无法访问串口设备：确认用户有权限访问设备（将用户加入 `dialout` 组或以 root 运行）。
- 端口被占用：检查是否有其他进程占用 SSH/HTTP 端口（`ss -ltnp` / `netstat -tlnp`）。
- 主机密钥提示：首次运行时会生成 `keys/ssh_host_rsa_key`，客户端会提示接受新主机密钥。
- 重新生成主机密钥：删除 `keys/ssh_host_rsa_key` 并重启程序即可生成新的密钥。

## 其他说明

- 日志与缓冲区大小可以通过 `buffer_size` 和 `log_dir` 配置调整。
- 如果需要将服务以容器或其他方式部署，请确保串口设备在容器中可见并拥有正确权限。

如果你希望我把 README 的格式调整为英文版、添加示例截图或生成 `requirements.txt` / systemd 单元的安装脚本，请告诉我。