201 lines
4.2 KiB
Markdown
201 lines
4.2 KiB
Markdown
# 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请求失败
|
||
- 检查请求格式和参数
|
||
- 查看服务器日志获取详细错误信息 |