# Stalwart 邮件 Web API 部署指南

本文档介绍如何将Stalwart邮件API客户端部署为Web服务，通过HTTP API提供邮箱管理功能。

## 特点

- RESTful API设计
- 默认使用API Key认证方式
- JSON格式请求和响应
- 支持所有命令行工具的功能
- 易于集成到现有系统

## API端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/create_user` | POST | 创建新邮箱用户 |
| `/api/list_users` | GET | 获取用户列表 |
| `/api/get_user` | GET | 获取单个用户信息 |
| `/api/get_emails` | POST | 获取用户邮件 |
| `/health` | GET | 健康检查 |

## 构建和部署

### 1. 编译Web服务器

```bash
cd go_stalwart_client
go build -o bin/stalwart-web-server cmd/web_server/main.go
```

### 2. 准备配置文件

确保`config/config.yaml`文件已正确配置，特别是API Key：

```yaml
api:
  base_url: https://mail.evnmail.com/api
  disable_proxy: true
user:
  default_domain: evnmail.com
  default_quota: 1073741824
auth:
  basic:
    username: admin
    password: your_password_here
  api_key: api_your_api_key_here
```

### 3. 部署到Linux服务器

#### 3.1 复制文件到服务器

```bash
# 创建目录
ssh user@your-server "mkdir -p /usr/local/bin /etc/stalwart"

# 复制可执行文件
scp bin/stalwart-web-server user@your-server:/usr/local/bin/

# 复制配置文件
scp config/config.yaml user@your-server:/etc/stalwart/

# 复制服务文件
scp stalwart-api.service user@your-server:/etc/systemd/system/
```

#### 3.2 设置权限

```bash
ssh user@your-server "chmod +x /usr/local/bin/stalwart-web-server"
```

#### 3.3 创建用户和组（如果需要）

```bash
ssh user@your-server "useradd -r -s /bin/false stalwart"
```

#### 3.4 生成API Token并更新服务文件

在服务器上运行一次Web服务器以生成API Token：

```bash
/usr/local/bin/stalwart-web-server -c /etc/stalwart/config.yaml
```

复制生成的API Token，然后更新服务文件：

```bash
sudo vim /etc/systemd/system/stalwart-api.service
# 将YOUR_API_TOKEN替换为生成的Token
```

#### 3.5 启动服务

```bash
sudo systemctl daemon-reload
sudo systemctl enable stalwart-api
sudo systemctl start stalwart-api
sudo systemctl status stalwart-api
```

### 4. 部署到Windows服务器

#### 4.1 使用NSSM（Non-Sucking Service Manager）

1. 下载NSSM: https://nssm.cc/download
2. 安装服务:

```
nssm install StalwartAPI D:\path\to\stalwart-web-server.exe -p 8080 -c D:\path\to\config.yaml -t YOUR_API_TOKEN
nssm set StalwartAPI AppDirectory D:\path\to\
nssm start StalwartAPI
```

## API使用示例

### 创建用户

```bash
curl -X POST http://your-server:8080/api/create_user \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@evnmail.com",
    "description": "新用户",
    "quota": 1073741824
  }'
```

响应:

```json
{
  "id": 123,
  "username": "newuser",
  "email": "newuser@evnmail.com",
  "password": "A8f2@xLp9q!Z",
  "success": true,
  "message": "用户创建成功"
}
```

### 获取用户列表

```bash
curl -X GET "http://your-server:8080/api/list_users?limit=10&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### 获取用户信息

```bash
curl -X GET "http://your-server:8080/api/get_user?email=user@evnmail.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### 获取邮件

```bash
curl -X POST http://your-server:8080/api/get_emails \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@evnmail.com",
    "password": "userpassword",
    "count": 5
  }'
```

## 注意事项

1. 安全性：
   - 使用HTTPS部署Web服务
   - 保护API Token，不要泄露
   - 定期更换API Token

2. 资源考虑：
   - 对于高负载环境，考虑增加服务器资源
   - 对于大规模部署，考虑负载均衡

3. 监控：
   - 定期检查服务状态
   - 设置日志轮转
   - 监控API调用频率和响应时间

## 故障排除

1. 服务无法启动
   - 检查配置文件路径是否正确
   - 确认API服务器地址可访问
   - 检查端口是否被占用

2. 认证失败
   - 确认API Token是否正确设置
   - 检查Authorization头格式

3. API请求失败
   - 检查请求格式和参数
   - 查看服务器日志获取详细错误信息