# MsgStackApi

**Repository Path**: Weixiaojun666/msgstackapi

## Basic Information

- **Project Name**: MsgStackApi
- **Description**: 鸿蒙原生APP 信栈的后端
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-17
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 信栈后端 · msgstack-api

HarmonyOS 应用「信栈 MsgStack」（`cn.zzwei.msgstack`）的自建服务端，Go 编写。
转发端（Unraid + EC20 等）把短信 / 来电上报到本服务，服务落库后经 MQ 异步调用
**华为 Push Kit** 下发到手机；App 也可主动拉取历史消息。

- 测试环境：`http://bj.zzwei.cn/msgstack`
- 线上环境：`https://api.zzwei.cn/msgstack`（CDN 回源到本机，路径前缀一致）

## 架构

```
转发端 ──POST /msgstack/{key}/push──▶ Go API ──▶ PostgreSQL（落库）
                                        │
                                        ├─▶ RabbitMQ（推送任务队列）
                                        │        └─▶ worker ──▶ 华为 Push Kit ──▶ 手机
                                        └─▶ Redis（设备缓存 / 限流 / 事件）

App ──GET /msgstack/{key}/message?since=0──▶ 拉取（推送不可达时的兜底通道）
```

依赖均可降级：Redis 挂了走本地缓存，RabbitMQ 挂了走内存队列，Push Kit 未配置则只落库。

## 接口

所有路径均挂在 `MSGSTACK_BASE_PATH`（默认 `/msgstack`）之下。
鉴权：请求头 `X-Api-Key`（或 `?key=`、`Authorization: Bearer`）等于 `device_key`，
或为管理员令牌 `MSGSTACK_ADMIN_TOKEN`。

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/health` | 健康检查，含 PG / Redis / MQ / Push 状态 |
| GET | `/` | 服务自述（CDN 连通性测试入口） |
| POST | `/register` | 注册设备，绑定 Push Token，返回 `device_key` |
| POST | `/bind` | 单独更新 Push Token |
| GET | `/{key}/info` | 设备信息 + 消息数 + 当前游标 |
| POST | `/{key}/push` | 上报一条短信/来电（入队并触发下发） |
| GET | `/{key}/message?since=&limit=&type=` | 增量拉取消息 |
| DELETE | `/{key}/message/{id}` | 删除单条 |
| DELETE | `/{key}/message` | 清空 |
| POST | `/{key}/message/{id}/read` | 标记已读 |
| GET | `/{key}/stream` | SSE 实时流（2s 轮询游标） |
| GET | `/admin/devices` | 设备列表（管理员） |
| GET | `/admin/stats` | 全局统计（管理员） |
| GET | `/static/...` | 静态资源，带 ETag + 长缓存，供 CDN 回源 |

### 注册设备

```bash
curl -X POST http://bj.zzwei.cn/msgstack/register \
  -H 'Content-Type: application/json' \
  -d '{"platform":"harmony","name":"我的Mate60","push_token":"<Push Kit Token>","bundle_name":"cn.zzwei.msgstack"}'
# => {"code":200,"data":{"device_key":"xY7...","push_url":"...","pull_url":"..."}}
```

### 上报一条短信

```bash
KEY=<device_key>
curl -X POST "http://bj.zzwei.cn/msgstack/$KEY/push" \
  -H 'Content-Type: application/json' -H "X-Api-Key: $KEY" \
  -d '{"type":"sms","sender":"10086","content":"【中国移动】您的验证码是 8842","id":"sms-1001"}'
```

`type` 为 `sms` 或 `call`；`id` 省略时服务端生成，重复 `id` 自动去重。

### 拉取 / 删除

```bash
curl -H "X-Api-Key: $KEY" "http://bj.zzwei.cn/msgstack/$KEY/message?since=0&limit=50"
curl -X DELETE -H "X-Api-Key: $KEY" "http://bj.zzwei.cn/msgstack/$KEY/message/sms-1001"
```

### 转发端最小示例（Unraid / 任意能跑 curl 的地方）

```bash
#!/usr/bin/env bash
KEY="你的device_key"
BASE="https://api.zzwei.cn/msgstack"
curl -sS -X POST "$BASE/$KEY/push" -H 'Content-Type: application/json' -H "X-Api-Key: $KEY" \
  -d "{\"type\":\"sms\",\"sender\":\"$1\",\"content\":\"$2\"}"
```

## 部署

```bash
# 1) 依赖
apt install -y postgresql redis-server rabbitmq-server nginx golang-go
systemctl enable --now postgresql redis-server rabbitmq-server nginx

# 2) 数据库
su - postgres -c "psql -c \"CREATE USER msgstack WITH PASSWORD 'MsgStack@2026' CREATEDB;\""
su - postgres -c "psql -c 'CREATE DATABASE msgstack OWNER msgstack;'"

# 3) 安装
make build                     # 产出 bin/msgstackapi
install -m 0755 bin/msgstackapi /opt/msgstackapi/msgstackapi
mkdir -p /etc/msgstackapi /var/www/msgstack/static /var/log/msgstackapi
cp deploy/msgstackapi.env /etc/msgstackapi/
cp deploy/msgstackapi.service /etc/systemd/system/
cp deploy/nginx-msgstack.conf /etc/nginx/conf.d/
useradd -r -s /usr/sbin/nologin msgstack || true
systemctl daemon-reload && systemctl enable --now msgstackapi
nginx -t && systemctl reload nginx
```

配置全部走 `/etc/msgstackapi/msgstackapi.env`，改完 `systemctl restart msgstackapi`。

## CDN 配置建议

| 路径规则 | 缓存 | 说明 |
|---|---|---|
| `/msgstack/static/*` | 缓存 1 天（跟随源站 `Cache-Control`） | 静态资源，回源 `/var/www/msgstack/static` |
| `/msgstack/stream` | **不缓存 + 关闭缓冲** | SSE 长连接 |
| `/msgstack/*`（其余） | **不缓存** | 动态接口，源站已下发 `no-store` |
| 回源协议 | 跟随 / HTTPS | 线上域名 `api.zzwei.cn` |
| 回源 Host | `api.zzwei.cn` | Nginx 里按 `server_name` 匹配 |

务必放行 `X-Api-Key`、`Authorization` 请求头，并传递 `X-Forwarded-For`
（服务已开启 `MSGSTACK_TRUST_PROXY=true`）。

## 环境变量

见 `deploy/msgstackapi.env`，关键项：

- `MSGSTACK_BASE_PATH` 路由前缀，线上必须 `/msgstack`
- `MSGSTACK_PG_DSN` PostgreSQL 连接串
- `MSGSTACK_RABBIT_URL` / `MSGSTACK_MQ_DRIVER`（`auto` | `rabbit` | `memory`）
- `MSGSTACK_PUSH_ENABLED` 与 `MSGSTACK_PUSH_CLIENT_ID/SECRET/PROJECT_ID`：华为 Push Kit 凭据
- `MSGSTACK_ADMIN_TOKEN` 管理接口令牌