Iris

Iris 是一个基于 Go 语言和 Charm 生态（Wish、Bubble Tea、Lip Gloss）构建的 SSH 终端即时通讯系统。用户通过标准的 SSH 客户端即可接入聊天服务器，在终端中体验频道聊天、私信沟通以及基于 Kitty Graphics 协议的行内高清图片渲染。

主要特性

• SSH 原生接入：基于标准 SSH 协议，客户端无需安装额外软件。
• 公钥身份认证：提取 SSH 公钥 SHA256 指纹进行用户鉴权与绑定。
• 终端 UI 界面：基于 Bubble Tea 与 Lip Gloss 构建三栏式终端界面，包含频道列表、聊天历史区与输入框。
• Kitty 行内图片渲染：支持 Kitty Graphics Protocol，在兼容终端（Ghostty、Kitty、WezTerm 等）内呈现高清图片，非兼容终端自动退回到文本/链接模式。
• 频道与私信系统：支持多频道群聊与基于用户昵称的点对点私信。
• Slash 斜杠指令：提供丰富指令用于频道管理、私信发送、昵称更新与图片发送。
• 数据持久化：使用 PostgreSQL 存储用户、频道、消息及媒体元数据，使用 sqlc 保证类型安全。

架构设计

• SSH 层 (internal/ssh)：管理主机密钥，处理公钥指纹提取并为每个会话分配终端 TUI 实例。
• TUI 层 (internal/tui)：管理用户 Onboarding 与 Chat 界面状态，处理键盘输入、图片粘贴解析与终端渲染。
• 消息总线 (internal/hub)：并发安全的中央 Pub/Sub 代理，负责频道消息广播与单播私信路由。
• 媒体处理 (internal/media)：处理本地存储、图片缩放与 Kitty 协议转码。
• 存储层 (internal/store)：封装 PostgreSQL 数据库操作。

环境要求

• Go 1.26+
• PostgreSQL 14+
• 支持 Kitty Graphics Protocol 的终端（推荐 Ghostty、Kitty 或 WezTerm）

快速开始

1. 配置环境变量

复制环境配置文件模版并按需修改：

cp .env.example .env

主要配置项说明：

配置项	默认值	说明
SSH_HOST	0.0.0.0	SSH 服务监听 IP 地址
SSH_PORT	2222	SSH 服务监听端口
SSH_HOST_KEY_PATH	.ssh/iris_ed25519	SSH 主机密钥文件路径
DATABASE_URL	postgres://postgres:postgres@localhost:5432/iris?sslmode=disable	PostgreSQL 连接字符串
UPLOAD_DIR	./uploads	上传图片保存路径
LOG_LEVEL	info	日志输出级别 (debug, info, warn, error)

2. 执行数据库迁移

在 PostgreSQL 正常运行且数据库已创建的前提下，执行数据库迁移：

make migrate-up

3. 编译并运行服务端

编译并直接启动：

make run

或仅编译生成二进制文件：

make build
./iris

4. 连接服务

使用标准 SSH 客户端连接：

ssh -p 2222 127.0.0.1

Plain ssh (without iris-term)

If you connect with a standard ssh client instead of iris-term, SSH does not forward the terminal-identity environment variables (TERM_PROGRAM, GHOSTTY_RESOURCES_DIR, etc.) that Iris uses to detect inline-image support. Two options:

1. Runtime override (easiest): after connecting, type /graphics kitty (or /graphics iterm2) to force-enable the image protocol for your session. Use /graphics auto to restore automatic detection, and /graphics none to disable.

2. SSH env forwarding: add to ~/.ssh/config:

   Host myiris
       HostName iris.example.com
       Port 2222
       SendEnv TERM_PROGRAM GHOSTTY_RESOURCES_DIR KITTY_WINDOW_ID WEZTERM_EXECUTABLE
   

   The Iris server accepts these env requests automatically; no server-side AcceptEnv configuration is needed.

首次连接将自动进入用户初始化流程，设置 Nickname 后即可开始聊天。

斜杠指令 (Slash Commands)

在聊天界面底部输入框中使用以下指令：

指令	说明	示例
/join <#channel>	加入或创建指定频道	/join #general
/leave	离开当前频道并返回 #general	/leave
/delete <#channel>	删除指定频道（仅 Admin，需二次确认；级联删除成员与历史）	/delete #test
/msg <@user> <内容>	向指定用户发送点对点私信	/msg @alice 你好
/nick <新昵称>	修改当前用户昵称	/nick bob
/topic <新主题>	修改当前频道的主题	/topic Go 语言交流
/who	列出当前频道的在线用户	/who
/image <URL或本地路径>	上传并发送行内图片	/image https://example.com/demo.png

项目结构

.
├── cmd/
│   └── iris/           # 程序入口 main.go
├── db/
│   ├── migrations/     # PostgreSQL 数据库迁移 SQL
│   └── queries/        # sqlc 源 SQL 查询定义
├── internal/
│   ├── config/         # 配置加载逻辑
│   ├── domain/         # 领域数据模型定义
│   ├── hub/            # 中央消息发布/订阅 Hub
│   ├── media/          # 本地存储、图片处理与 Kitty 协议转码
│   ├── ssh/            # SSH 服务与公钥身份认证
│   ├── store/          # sqlc 生成的数据库持久层
│   └── tui/            # Bubble Tea 视图模型与渲染
├── Makefile            # 项目构建与常用运维指令
└── sqlc.yaml           # sqlc 代码生成配置

开发与构建命令

make build         # 编译生成的二进制文件 iris
make run           # 编译并运行服务端
make test          # 执行单元测试
make generate      # 重新运行 sqlc 生成 Go 代码
make migrate-up    # 应用数据库迁移
make migrate-down  # 回滚数据库迁移
make clean         # 清理构建产物