# ssh-tool-server

**Repository Path**: rymaker/ssh-tool-server

## Basic Information

- **Project Name**: ssh-tool-server
- **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-07-30
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SSH Sync Server

SSH 端口映射工具的账号、端到端加密配置同步服务与 Web 管理后台。

技术栈：

- Nuxt 4 / Nitro / Vue 3
- TypeORM 1.1
- MySQL 8.4 LTS
- Nuxt UI
- Argon2id、JWT、TOTP MFA

服务端只保存客户端生成的加密信封。管理页面无法查看或下载用户的 SSH 地址、密码、
私钥、wrapped key 或同步密文正文。

## 当前实现

- 桌面端注册、登录、密码修改、refresh token 轮换、当前设备退出和全部设备退出；
- 注册邀请码、管理员一次性生成/停用和使用次数控制；
- 注册、登录、refresh 和管理员登录的 MySQL 持久化限流；
- 管理端配置的新用户默认设备、文档和历史版本配额；
- 用户设备列表、重命名和撤销；
- 端到端加密 Vault key envelope 存储、重新包装及重新认证后的 Vault 删除；
- 当前密码 + ETag + 幂等键保护的原子 Vault 密钥轮换和旧历史清理；
- 同步文档上传、下载和 HEAD revision；
- 客户端可复用的严格加密信封、Vault 信封、ETag 和幂等键 Zod 协议；
- 同步历史 revision 元数据列表、有界游标分页、幂等历史恢复和主动清除；
- `If-Match` 乐观锁、幂等键、历史版本保留、配额及 MySQL 死锁有限重试；
- 管理员密码 + TOTP MFA 登录；
- 管理员 Cookie 会话、CSRF 防护和 RBAC；
- 管理仪表盘、用户详情/配额、设备、Vault/revision 安全元数据、审计和系统设置页面；
- 管理端系统健康 API 与页面；
- 管理审计筛选和带 CSV 注入防护的白名单导出；
- Super Admin 通过密码、TOTP、CSRF 和确认词执行用户/Vault 永久删除；
- TypeORM 实体和初始 migration；
- 数据库连通性及待执行 migration 就绪检查；
- MySQL 原生连接、InnoDB 锁等待和服务端 SELECT 执行超时；
- TypeORM 与 Nitro 统一 JSON 安全日志边界，输出请求状态和耗时，不记录 SQL 参数、请求数据或错误堆栈；
- Nitro 启动期严格校验数据库 URL、JWT/MFA、TTL、配额、超时和布尔配置；
- Docker Compose 部署（外部 MySQL）。

服务端和 `E:\code\ssh-tool` Electron 客户端的仓库内功能均已完成。客户端正式构建
从其仓库根目录 `.env` 读取公开变量 `SSH_TOOL_SYNC_API_URL` 并写入主进程 bundle；
数据库、JWT、MFA 等本仓库服务端秘密不会进入客户端。公开运营所需的邮件密码找回
仍是可选后续能力；第一版采用 Super Admin 仓库外核验后删除旧账号、重新签发邀请码
的替代流程，不允许管理员代设临时密码。

服务端允许直接使用 HTTP 和 IP 地址。Docker 默认只监听 `127.0.0.1:3000`；如需让
局域网设备访问，在本仓库 `.env` 中设置：

```dotenv
SSH_TOOL_SERVER_BIND_HOST=0.0.0.0
SSH_TOOL_SERVER_PORT=3000
```

随后客户端可配置 `SSH_TOOL_SYNC_API_URL=http://服务器IP:3000`。HTTP 不加密账号密码
和 token 的传输，公网部署仍建议使用 HTTPS。

## 本地启动

复制环境变量：

```powershell
Copy-Item .env.example .env
```

生成 JWT 和管理员 MFA 加密密钥：

```powershell
node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
```

把结果分别填入 `.env` 的 `NUXT_JWT_SECRET` 和 `NUXT_ADMIN_MFA_KEY`。

启动 MySQL（可使用外部 MySQL 或 Docker）：

```powershell
# 使用 Docker 启动本地 MySQL
docker run -d --name ssh-tool-mysql \
  -e MYSQL_DATABASE=ssh_tool \
  -e MYSQL_USER=ssh_tool \
  -e MYSQL_PASSWORD=change-me \
  -e MYSQL_ROOT_PASSWORD=change-root-me \
  -p 127.0.0.1:3306:3306 \
  mysql:8.4

# 或使用已有的外部 MySQL，在 .env 中配置连接信息
```

执行 migration：

```powershell
npm install
npm run db:migrate
```

创建首个超级管理员：

```powershell
$env:ADMIN_EMAIL='admin@example.com'
$env:ADMIN_PASSWORD='replace-with-a-strong-password'
$env:ADMIN_ROLE='super_admin' # 也可使用 operator 或 auditor
npm run admin:create
```

管理员账号第一版只通过服务器 CLI 创建；命令会显示一次 TOTP 密钥和 URI。
保存到身份验证器后删除终端历史中的敏感内容。

启动 Nuxt：

```powershell
npm run dev
```

管理页面位于 `http://127.0.0.1:3000/admin/login`。

日志默认以单行 JSON 输出到 stdout/stderr，可直接查看：

```powershell
docker compose logs -f app
```

`.env` 中可设置 `NUXT_LOG_LEVEL=debug|info|warn|error|silent`，并使用
`NUXT_LOG_REQUESTS=true|false` 开关 HTTP 请求日志。请求日志只包含时间、请求 ID、
方法、无查询参数的路径、状态码和耗时；不会输出 Authorization、Cookie、密码、token、
私钥、请求体、SQL 参数或同步密文。

## 验证

```powershell
npm run typecheck
npm test
npm run build
```

安装 Docker 后可以运行真实 MySQL API 集成测试：

```powershell
npm run test:integration
```

该命令会自动构建服务端、启动临时 MySQL 8.4 容器，并验证邀请码、默认配额、
认证限流、refresh token 重放与整族吊销、用户水平越权、管理员 CSRF/RBAC、
revision 并发冲突、相同幂等键并发重试、畸形/超限密文和敏感日志泄漏；
还会验证事务末端故障回滚、过期幂等键、服务进程重启、MySQL 停机恢复、
迁移就绪状态、同步历史数据隔离/恢复/清除、设备重命名、全部退出、密码修改、
key envelope 更新、原子密钥轮换、用户/管理员侧账号与 Vault 删除、管理端健康、
安全详情、审计 CSV 导出及 MySQL 1213 死锁重试；
测试结束后自动删除临时容器。

## 生产要求

- 必须置于 HTTPS 反向代理之后；
- 替换所有默认数据库密码；
- JWT 和 MFA 加密密钥使用 secret manager 管理；
- 设置 `NUXT_ADMIN_COOKIE_SECURE=true`，并只通过 HTTPS 访问管理页面；
- 只有在应用位于可信反向代理之后时才设置 `NUXT_TRUST_PROXY=true`；
- 部署时先执行 `npm run db:migrate`；
- 不得开启 TypeORM `synchronize`；
- 根据部署环境设置数据库连接、锁等待和 SELECT 超时；这些设置不替代反向代理、
  网络和基础设施对长写操作及失联连接的超时保护；
- 定期备份 MySQL 并验证恢复；
- 首个管理员只能通过服务器 CLI 创建。

完整实施规划见 [SYNC_PLAN.md](./SYNC_PLAN.md)。