httpsms 是一个让你通过 HTTP API 用安卓手机收发短信的服务。它主要由四个部分组成：

  • Web UI：用户界面，用于管理。
  • API 服务：核心后端，处理请求和业务逻辑。
  • Android 应用：安装在手机上，接收推送指令并真正执行短信收发。
  • 数据库与缓存：用于存储数据和临时信息。

其自托管部署基于 Docker Compose，这会将 API、Web UI、PostgreSQL 数据库和 Redis 缓存一并容器化。

以下是部署的全流程图，可以帮你建立整体概念：

📝 详细部署步骤

第一步：准备工作

在你的服务器或电脑上准备好运行环境。

  1. 安装 Docker 和 Docker Compose：确保系统已安装。

  2. 克隆代码仓库：

    1
    2
    git clone https://github.com/NdoleStudio/httpsms.git
    cd httpsms

第二步：配置 Firebase（关键步骤）

项目使用 Firebase 进行用户认证和推送通知，这是必须配置的核心环节。

  1. 创建 Firebase 项目：访问 Firebase 控制台 创建一个新项目。
  2. 获取 Web SDK 配置：在项目设置中，找到您的 Web 应用，记录下 firebaseConfig 对象中的所有字段值（如 apiKey, authDomain 等）。这些稍后要填入环境变量。
  3. 启用邮箱/密码登录：在 “Authentication” > “Sign-in methods” 中，启用 “Email/Password”。特别注意：根据项目说明，你需要禁用“邮箱枚举保护”才能正常登录。
  4. 生成服务账号密钥：在 “Project Settings” > “Service accounts” 中，点击“生成新的私钥”，下载 JSON 文件并重命名为 firebase-credentials.json，放在项目 api 目录下备用。
  5. 生成 Android 配置文件：在 Firebase 控制台按指引添加 Android 应用，下载 google-services.json 文件，用于后续构建 Android App。

第三步：设置 SMTP 邮件服务

项目需要通过 SMTP 发送通知邮件（如手机离线提醒）。

  • 你可以使用 Mailtrap 等服务获取开发用的 SMTP 服务器地址、端口、用户名和密码，并记录下来备用。

第四步：配置 Cloudflare Turnstile

为了保护消息搜索接口，需要配置验证码服务。

  1. 在 Cloudflare 仪表盘找到 Turnstile，添加一个新站点，域名填写你的自托管域名（本地开发可用 localhost）。
  2. 记录下生成的 Site Key 和 Secret Key。

第五步：配置环境变量

这是将前面准备的所有信息填入配置文件的关键步骤。

  • 配置 Web UI (web/.env)：

    1
    cp web/.env.docker web/.env

    编辑 web/.env 文件，填入之前获取的 Firebase Web SDK 配置和 Cloudflare Turnstile Site Key。

    1
    2
    3
    4
    FIREBASE_API_KEY=您的apiKey
    FIREBASE_AUTH_DOMAIN=您的authDomain
    # ... 其他 FIREBASE_ 变量
    CLOUDFLARE_TURNSTILE_SITE_KEY=您的Cloudflare站点密钥

  • 配置 API (api/.env)：

    1
    cp api/.env.docker api/.env

    编辑 api/.env 文件，填入之前准备的各项敏感信息。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    # SMTP 配置
    SMTP_USERNAME=您的SMTP用户名
    SMTP_PASSWORD=您的SMTP密码
    SMTP_HOST=您的SMTP主机地址
    SMTP_PORT=您的SMTP端口

    # Firebase 配置
    FIREBASE_CREDENTIALS=./firebase-credentials.json  # 指向你下载的JSON文件
    GCP_PROJECT_ID=您的Firebase项目ID

    # Cloudflare Turnstile
    CLOUDFLARE_TURNSTILE_SECRET_KEY=您的Cloudflare Secret Key

    # 系统用户配置（先随便填，之后要手动创建并保持统一）
    EVENTS_QUEUE_USER_API_KEY=生成一个随机强密码
    EVENTS_QUEUE_USER_ID=生成一个随机用户ID

第六步：构建并运行

现在可以通过 Docker Compose 一键启动所有服务。

1
docker compose up --build

首次运行会下载并构建镜像，需要一些时间。成功后，你应能通过 http://localhost:3000 访问 Web 界面，API 地址为 http://localhost:8000。

第七步：创建系统用户

项目需要一个“系统用户”来处理后台异步任务，需要手动在数据库中创建。

  1. 连接到 Docker 启动的 PostgreSQL 数据库。

  2. 执行 SQL 语句，其中的 id 和 api_key 必须与 api/.env 文件中设置的 EVENTS_QUEUE_USER_ID 和 EVENTS_QUEUE_USER_API_KEY 完全一致。

    1
    2
    INSERT INTO users (id, api_key, email) 
    VALUES ('您在.env中设置的ID', '您在.env中设置的API密钥', 'system@domain.com');

  3. 插入成功后，重启 API 容器使环境变量生效。

第八步：构建 Android 应用

现在需要构建手机端的 App。

  1. 用 Android Studio 打开项目中的 android 目录。
  2. 将你在第二步下载的 google-services.json 文件复制到 android/app/ 目录，替换原有文件。
  3. 连接一部安卓手机或使用模拟器，编译并运行项目。安装成功后，App 就能与你的自建服务器通信了。

✅ 测试部署（可选但推荐）

项目提供了集成测试脚本来验证所有组件是否正常。

1
2
3
4
5
6
7
cd tests
bash generate-firebase-credentials.sh
export FIREBASE_CREDENTIALS=$(jq -c . firebase-credentials.json)
docker compose up -d --build --wait
docker compose wait seed && sleep 2
go test -v -timeout 120s ./...
docker compose down -v

📚 扩展信息

全部配置完成后，你就可以通过调用 HTTP API 来让手机发送短信，或接收手机收到的短信了。