# Comini

**Repository Path**: fexcode/comini

## Basic Information

- **Project Name**: Comini
- **Description**: 超级轻量级的类ssh加密远程shell
专为嵌入式设计
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# comini (Connect Mini)

超轻量级远程 Shell 工具，专为资源受限环境设计。

> 客户端二进制仅 **49KB**，适合 Linux 服务器与 ESP32 嵌入式设备。

## 特性

- **超轻量** — 客户端 < 512KB，服务器 < 100MB
- **安全通信** — AES-128-CTR 加密 + HMAC-SHA256 完整性校验
- **跨平台** — 支持 Linux x86_64（计划支持 ESP32）
- **简单部署** — 无复杂依赖，编译即用
- **自定义协议** — 专为低资源环境优化的二进制协议

## 架构

```
┌─────────────┐       TCP (端口 2222)       ┌─────────────┐
│  comini     │  ◄─────────────────────────►│  comini     │
│  _client    │   register / login / cmd    │  _server    │
│  (49KB)     │                             │  (50KB)     │
└─────────────┘                             └─────────────┘
   内存 < 512KB                                功能优先
   ESP32 / Linux                               Linux 服务器
```

## 快速开始

### 依赖

```bash
# Ubuntu / Debian
sudo apt install build-essential libmbedtls-dev

# Arch Linux
sudo pacman -S base-devel mbedtls

# CentOS / RHEL
sudo yum groupinstall "Development Tools"
sudo yum install mbedtls-devel
```

### 编译

```bash
git clone https://gitee.com/fexcode/comini.git
cd comini
make
```

编译产物：
- `comini_server` — 服务器端程序
- `comini_client` — 客户端程序
- `comini.a` — 静态库

### 部署服务器

```bash
# 启动服务器（默认端口 2222）
./comini_server

# 指定端口
./comini_server 3333
```

默认用户：
| 用户名 | 密码 |
|--------|------|
| admin  | admin123 |
| user   | user123 |
| test   | test123 |

### 连接服务器

```bash
# 连接本地服务器
./comini_client localhost

# 连接远程服务器（指定端口）
./comini_client 192.168.1.100 2222
```

连接后可选择：
1. **注册新用户** — 创建新账户
2. **用户登录** — 使用已有账户登录
3. **退出** — 关闭客户端

登录成功后进入交互式 Shell，输入命令即可远程执行：

```
comini> uname -a
Linux server 5.15.0 #1 SMP x86_64 GNU/Linux
[命令退出码: 0]

comini> whoami
root

comini> exit
再见!
```

## 命令参考

| 命令 | 说明 |
|------|------|
| `help` | 显示帮助信息 |
| `exit` | 退出连接 |
| `quit` | 退出连接 |
| 其他 | 作为 shell 命令发送到服务器执行 |

## 项目结构

```
comini/
├── include/
│   └── comini.h          # 公共头文件（协议、加密、Shell 接口）
├── src/
│   ├── protocol.c        # 协议处理（消息序列化/反序列化）
│   ├── crypto.c          # 加密模块（AES-128-CTR, HMAC-SHA256）
│   ├── shell.c           # Shell 模块（命令执行）
│   ├── server.c          # 服务器端（监听、用户管理、命令转发）
│   └── client.c          # 客户端（连接、交互、命令发送）
├── tests/
│   ├── test_protocol.c   # 协议测试
│   ├── test_crypto.c     # 加密测试
│   └── test_shell.c      # Shell 测试
├── Makefile              # 构建脚本
├── DEVELOPMENT.md        # 开发规范
└── TODOS.md              # 待办事项
```

## 技术规格

| 指标 | 数值 |
|------|------|
| 协议消息头 | 8 字节 |
| 加密算法 | AES-128-CTR |
| 完整性校验 | HMAC-SHA256 |
| 客户端二进制 | ~49KB |
| 服务器二进制 | ~50KB |
| 默认端口 | 2222 |

## 部署指南

### Ubuntu 服务器部署

```bash
# 1. 安装依赖
sudo apt update
sudo apt install -y build-essential libmbedtls-dev

# 2. 克隆并编译
git clone https://gitee.com/fexcode/comini.git
cd comini
make

# 3. 启动服务器
./comini_server 2222

# 4. （可选）后台运行
nohup ./comini_server 2222 > comini.log 2>&1 &

# 5. （可选）设置开机自启
sudo cp comini_server /usr/local/bin/
sudo tee /etc/systemd/system/comini.service << 'EOF'
[Unit]
Description=Comini Remote Shell Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/comini_server 2222
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable comini
sudo systemctl start comini
```

### Termux (Android) 客户端部署

```bash
# 1. 安装依赖
pkg update
pkg install -y git make mbedtls

# 2. 克隆并编译
git clone https://gitee.com/fexcode/comini.git
cd comini
make

# 3. 连接服务器
./comini_client <服务器IP> 2222
```

> **注意**：Termux 中编译时如有警告可忽略，不影响功能。

### 防火墙配置

```bash
# Ubuntu ufw
sudo ufw allow 2222/tcp

# CentOS firewalld
sudo firewall-cmd --permanent --add-port=2222/tcp
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p tcp --dport 2222 -j ACCEPT
```

## 内存目标

| 组件 | 目标 | 当前 |
|------|------|------|
| 客户端 | < 512KB | ~49KB ✅ |
| 服务器 | < 100MB | ~50KB ✅ |

## 开发

```bash
# 运行测试
make test          # 协议测试
make test_crypto   # 加密测试
make test_shell    # Shell 测试

# 清理
make clean
```

## 路线图

- [x] 自定义二进制协议
- [x] AES-128-CTR 加密
- [x] 用户注册/登录
- [x] 远程命令执行
- [ ] 完整握手协议和密钥交换
- [ ] 输出流式传输
- [ ] 客户端内存深度优化
- [ ] ESP32 移植
- [ ] 文件传输

## 协议设计

```
消息格式 (8 字节头部 + 变长载荷):
┌────────┬────────┬──────────┬───────────┐
│ Magic  │ Type   │ Length   │ Sequence  │
│ 1 byte │ 1 byte │ 2 bytes  │ 4 bytes   │
└────────┴────────┴──────────┴───────────┘

加密消息:
┌─────────────┬─────────────┬─────────────┐
│ IV (16B)    │ Ciphertext  │ HMAC (32B)  │
└─────────────┴─────────────┴─────────────┘
```

## 许可证

MIT License

## 链接

- 仓库：https://gitee.com/fexcode/comini