sdd

2025-05-23 23:08:02 +08:00
parent 9444bf4802
commit a8d25054fc
14 changed files with 2277 additions and 0 deletions
--- a/WEB_API_DEPLOYMENT.md
+++ b/WEB_API_DEPLOYMENT.md
@@ -0,0 +1,201 @@
+# 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请求失败
+   - 检查请求格式和参数
+   - 查看服务器日志获取详细错误信息