mirror of
https://github.com/wu736139669/hapi.git
synced 2026-08-05 06:24:37 +00:00
weishu
6505c58bf3
- Make TELEGRAM_BOT_TOKEN and ALLOWED_CHAT_IDS optional environment variables - Add telegramEnabled flag to conditionally initialize the bot on startup - Introduce persistent owner ID for unified user identity across web and Telegram auth - Update Telegram bot to accept configuration in constructor instead of using global config - Handle empty allowlist by showing chat ID prompt on /start command - Use owner ID instead of Telegram user ID for API authentication - Add conditional Telegram support checks in auth routes with clear error messages - Update documentation to explain optional Telegram configuration and binding workflow - Rename telegramUserId to userId in auth middleware for clarity
82 lines
2.6 KiB
Markdown
82 lines
2.6 KiB
Markdown
# hapi-server
|
|
|
|
Telegram bot + HTTP API + realtime updates for hapi.
|
|
|
|
## What it does
|
|
- Telegram bot for notifications and the Mini App entrypoint.
|
|
- HTTP API for sessions, messages, permissions, machines, and files.
|
|
- Server-Sent Events stream for live updates in the web app.
|
|
- Socket.IO channel for CLI connections.
|
|
- Serves the web app from `web/dist` or embedded assets in the single binary.
|
|
- Persists state in SQLite.
|
|
|
|
## Typical deployment flow
|
|
1. Configure env vars.
|
|
2. Expose the server to the internet (HTTPS) if you need Telegram Mini App access.
|
|
3. Run the server.
|
|
4. Point the CLI to the server and open the web app.
|
|
|
|
## Configuration
|
|
Required:
|
|
- `CLI_API_TOKEN` - shared secret used by CLI and web login.
|
|
|
|
Optional (Telegram):
|
|
- `TELEGRAM_BOT_TOKEN` - token from @BotFather.
|
|
- `ALLOWED_CHAT_IDS` - comma-separated chat IDs allowed to use the bot.
|
|
- `WEBAPP_URL` - public HTTPS URL for Telegram Mini App access.
|
|
|
|
Optional:
|
|
- `WEBAPP_PORT` - HTTP port (default: 3006).
|
|
- `CORS_ORIGINS` - comma-separated origins, or `*`.
|
|
- `HAPI_HOME` - data directory (default: ~/.hapi).
|
|
- `DB_PATH` - SQLite database path.
|
|
|
|
## Running
|
|
Binary (single executable):
|
|
```bash
|
|
export TELEGRAM_BOT_TOKEN="..."
|
|
export ALLOWED_CHAT_IDS="12345678"
|
|
export CLI_API_TOKEN="shared-secret"
|
|
export WEBAPP_URL="https://your-domain.example"
|
|
|
|
hapi server
|
|
```
|
|
|
|
If you only need web + CLI, you can omit TELEGRAM_BOT_TOKEN and ALLOWED_CHAT_IDS.
|
|
To enable Telegram, set TELEGRAM_BOT_TOKEN and WEBAPP_URL, start the server, send `/start`
|
|
to the bot to get your chat ID, set ALLOWED_CHAT_IDS, and restart the server.
|
|
|
|
From source:
|
|
```bash
|
|
bun install
|
|
bun run dev:server
|
|
```
|
|
|
|
Or inside `server/`:
|
|
```bash
|
|
bun run start
|
|
```
|
|
|
|
## Build for deployment
|
|
From the repo root:
|
|
```bash
|
|
bun run build:server
|
|
bun run build:web
|
|
```
|
|
|
|
The server build output is `server/dist/index.js`, and the web assets are in `web/dist`.
|
|
|
|
## Networking notes
|
|
- Telegram Mini Apps require HTTPS and a public URL. If the server has no public IP, use Cloudflare Tunnel or Tailscale and set `WEBAPP_URL` to the HTTPS endpoint.
|
|
- If the web app is hosted on a different origin, set `CORS_ORIGINS` accordingly.
|
|
|
|
## Architecture overview
|
|
The server is the hub for direct-connect mode. It accepts CLI connections over Socket.IO, exposes HTTP endpoints for the web UI, and publishes live updates over SSE. A Telegram bot provides notifications and a Mini App entrypoint. Session and machine state are stored in a local SQLite database.
|
|
|
|
## Security model
|
|
Access is controlled by:
|
|
- Telegram chat ID allowlist (when Telegram is enabled).
|
|
- `CLI_API_TOKEN` shared secret for CLI and browser access.
|
|
|
|
Transport security depends on HTTPS in front of the server.
|