TUI 终端用户界面

Shortlinker 提供了一个交互式的终端用户界面（TUI），让你可以在命令行中可视化管理短链接。

启动 TUI

./shortlinker tui

界面概览

TUI 界面主要分为以下几个区域：

┌─────────────────────────────────────────────────────────┐
│  Shortlinker - Terminal UI                             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  短码         目标 URL                    点击数  状态  │
│  ────────────────────────────────────────────────────  │
│  github       https://github.com          142    活跃  │
│  google       https://google.com           89    活跃  │
│  temp         https://example.com           5    过期  │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  详情面板                                               │
│  短码: github                                          │
│  目标: https://github.com                              │
│  创建时间: 2024-12-01 10:30:22                         │
│  过期时间: 永不过期                                     │
│  点击次数: 142                                         │
│  密码保护: 否                                          │
└─────────────────────────────────────────────────────────┘
  q:退出  x:导出/导入  /:搜索  ↑↓:导航  Enter:详情

快捷键

主界面操作

快捷键	功能
↑ / ↓	向上/向下移动选择
PageUp / PageDown	翻页（每次 10 条）
Home / g	跳到顶部
End / G	跳到底部
/	搜索（短码 / 目标 URL 模糊匹配）
Enter / v	查看详情
? / h	打开帮助
a	添加新短链接
e	编辑选中的短链接
d	删除选中的短链接
x	导出/导入菜单
q	退出（会弹出确认）

添加/编辑界面操作

快捷键	功能
Tab	切换输入字段
Enter	保存链接
Esc	取消并返回
Space	切换强制覆盖（仅添加界面，且需要焦点在短码字段）

功能说明

1. 浏览链接列表

主界面显示所有短链接的概览信息：

• 短码：短链接的代码（青色）
• 目标 URL：重定向的目标地址（蓝色）
• 过期时间：显示过期时间或 (EXPIRED) 标记（黄色/红色）
• 密码保护：显示 🔒 图标（紫色）
• 点击数：显示访问次数（绿色）

高亮选中项会以灰色背景显示。

2. 添加新链接 (按 a)

进入添加界面后，可以配置：

• 短码（Short Code）：留空自动生成随机码
• 目标 URL（Target URL）：必填，必须以 http:// 或 https:// 开头
• 过期时间（Expire Time）：可选，支持相对时间（如 1d, 7d）或 RFC3339 格式
• 密码（Password）：可选，密码保护功能（实验性）
• 强制覆盖：勾选后可覆盖已存在的短码

操作：

• 按 Tab 键在各字段间切换
• 按 Space 切换"强制覆盖"（需要焦点在短码字段）
• 按 Enter 保存
• 按 Esc 取消

3. 编辑现有链接 (按 e)

编辑界面与添加类似，但短码字段为只读。可以修改：

• 目标 URL
• 过期时间
• 密码（留空保持原密码）

注意：创建时间和点击计数会被保留。

4. 删除链接 (按 d)

会弹出确认对话框显示链接详情，按 y 确认删除，按 n 取消。

警告：删除操作不可撤销！

5. 导出/导入（按 x）

导出功能：

• 默认会给出一个时间戳文件名（如 shortlinks_export_20250115_183000.csv），可编辑修改
• 导出所有链接为 CSV 格式（带 header）
• 可用于备份或迁移

导入功能：

• 通过文件浏览器选择要导入的 .csv 文件（.json 仅兼容旧格式，已废弃）
• 批量导入链接（逐条 upsert：同短码会被覆盖）
• 与 CLI 的导出格式兼容

6. 自动通知服务器

所有增删改（以及导入）完成后，TUI 会自动通知服务器重新加载短链接数据/缓存（Unix: SIGUSR1；Windows: 触发文件）。

配色方案

TUI 使用不同颜色标识链接状态：

• 🟢 绿色：活跃链接
• 🔴 红色：已过期链接
• 🔵 蓝色：受保护链接
• ⚪ 灰色：选中高亮

使用场景

TUI 模式适用于以下场景：

1. 可视化管理：直观的界面，适合快速 CRUD 操作
2. 无需 API：不需要配置 Admin API Token 或启动 Web 服务
3. 服务器管理：在 SSH 终端中完整管理短链接
4. 批量操作：导出/导入功能方便迁移和备份
5. 即时反馈：操作立即生效，无需等待 API 响应

限制说明

当前版本 TUI 的已知限制：

• ⚠️ 不支持批量选择和批量操作（计划中）
• ⚠️ 密码输入显示为遮罩，无法看到实际内容

故障排除

界面显示异常

# 确保终端支持 UTF-8
export LANG=en_US.UTF-8

# 调整终端窗口大小（建议至少 80x24）

无法启动 TUI

# 检查存储后端是否可访问
./shortlinker list

# 查看错误日志
RUST_LOG=debug ./shortlinker tui

数据不刷新

当前版本没有手动刷新快捷键：

• 增删改/导入完成后会自动刷新列表
• 若你正在搜索状态，可按 Esc 清除搜索条件
• 仍不刷新时，可退出后重新进入 TUI

与其他工具对比

功能	TUI	CLI	Admin API	Web Panel
查看链接	✅	✅	✅	✅
创建链接	✅	✅	✅	✅
编辑链接	✅	✅	✅	✅
删除链接	✅	✅	✅	✅
导出/导入	✅	✅	✅（CSV）	✅
可视化界面	✅	❌	❌	✅
需要鉴权	❌	❌	✅	✅
实时交互	✅	❌	❌	✅
批量操作	⚠️ 导入	✅	✅	✅
远程访问	❌	❌	✅	✅

下一步

• 📋 学习 CLI 命令 进行链接管理操作
• 🛡️ 使用 Admin API 进行编程式管理
• 🎨 尝试 Web 管理界面 进行图形化管理