yiekheng 45303d00aa Refactor: externalize all hardcoded config to env vars, add multi-deployment support

- Remove all hardcoded credentials and config from Python source code:
  - db.py: DB host/user/password/name/port → env vars with connection retry support
  - cm_bot_hal.py: prefix, agent_id, agent_password, security_pin → env vars
  - cm_bot.py: base_url → env var, fix register_user return values
  - cm_web_view.py: hardcoded '13c' prefix → configurable CM_PREFIX_PATTERN
  - cm_telegram.py: hardcoded 'Sky533535' pin → env var CM_SECURITY_PIN

- Parameterize docker-compose.yml for multi-deployment on same host:
  - Container names use ${CM_DEPLOY_NAME} prefix (e.g. rex-cm-*, siong-cm-*)
  - Network name uses ${CM_DEPLOY_NAME}-network
  - Web view port configurable via ${CM_WEB_HOST_PORT}
  - All service config passed as env vars (not baked into image)

- Add per-deployment env configs:
  - envs/rex/.env (port 8001, prefix 13c, DB rex_cm)
  - envs/siong/.env (port 8005, prefix 13sa, DB siong_cm)
  - .env.example as template for new deployments
  - Remove .env from .gitignore (local server, safe to commit)

- Improve telegram bot reliability:
  - Add retry logic for polling with exponential backoff
  - Add error handlers for Conflict, RetryAfter, NetworkError, TimedOut
  - Add /9 command to show chat ID
  - Add telegram_notifier.py for alert notifications
  - Fix error handling in /2 and /3 command handlers

- Fix db.py cursor cleanup (close cursor before connection in finally blocks)
- Fix docker-compose.override.yml environment syntax (list → mapping)
- Update README with multi-deployment instructions
- Add AGENTS.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-22 22:25:40 +08:00

4.6 KiB

Raw Permalink Blame History

Repository Guidelines

Project Structure & Module Organization

app/ contains service modules:
- cm_api.py (Flask API, serves on 3000)
- cm_web_view.py (Flask UI, container 8000, host 8001)
- cm_telegram.py (Telegram bot + account monitor thread)
- cm_transfer_credit.py (scheduled transfer worker)
- db.py (MySQL connection/retry logic)
docker/<service>/Dockerfile builds one image per service (cm-api, cm-web, cm-telegram, cm-transfer).
docker-compose.yml uses registry images; docker-compose.override.yml swaps to local builds.
scripts/local_build.sh starts local compose; scripts/publish.sh builds and pushes all images via buildx.

Reproduce From Scratch (Clean Machine)

Install prerequisites:
- Docker Engine + Docker Compose v2
- MySQL 8+ reachable by containers
- Telegram bot token(s) for bot and optional alerting

Clone and enter repo:

git clone <repo-url> cm_bot_v2
cd cm_bot_v2

Create .env at repo root for compose interpolation:

CM_IMAGE_PREFIX=local
DOCKER_IMAGE_TAG=dev
TELEGRAM_BOT_TOKEN=<required>
TELEGRAM_ALERT_CHAT_ID=<optional>
TELEGRAM_ALERT_BOT_TOKEN=<optional>
CM_TRANSFER_MAX_THREADS=1

Prepare MySQL schema (minimum required):

CREATE DATABASE rex_cm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE rex_cm;

CREATE TABLE acc (
  username VARCHAR(64) PRIMARY KEY,
  password VARCHAR(128) NOT NULL,
  status   VARCHAR(32) DEFAULT '',
  link     VARCHAR(512) DEFAULT ''
);

CREATE TABLE user (
  f_username       VARCHAR(64) PRIMARY KEY,
  f_password       VARCHAR(128) NOT NULL,
  t_username       VARCHAR(64) NOT NULL,
  t_password       VARCHAR(128) NOT NULL,
  last_update_time TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

Seed at least one acc.username matching prefix 13c... (required by CM_BOT_HAL.get_next_username()), for example:
```
INSERT INTO acc (username, password, status, link) VALUES ('13c1000', 'seed', '', '');
```
Configure DB connection values:
- Default fallback is hardcoded in app/db.py (DB_HOST=192.168.0.210, etc.).
- For reliable reproduction, add DB_HOST, DB_USER, DB_PASSWORD, DB_NAME, DB_PORT to service environment: in compose files (at minimum api-server, telegram-bot, transfer-bot).

Start services locally:

docker compose -f docker-compose.yml -f docker-compose.override.yml up --build

Or run bash scripts/local_build.sh (uses sudo by default).

Build, Test, and Development Commands

python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt: optional non-Docker local env.
docker compose -f docker-compose.yml -f docker-compose.override.yml up --build: local dev stack.
docker compose up -d: run prebuilt/published images.
bash scripts/publish.sh <tag>: build + push all service images (gitea.04080616.xyz/yiekheng).

Verification Checklist

API responds: curl http://localhost:3000/acc/
Web UI loads: open http://localhost:8001

Service logs are clean:

docker compose logs -f api-server web-view telegram-bot transfer-bot

Telegram bot validates with /menu and /9 in chat after startup.

Coding Style & Naming Conventions

Python 3.9, 4-space indentation, snake_case for variables/functions, module names as cm_<role>.py.
Preserve existing class names (CM_API, CM_BOT, CM_BOT_HAL).
Keep environment variable names uppercase and document new ones in this file.
No enforced formatter/linter in-repo; match the surrounding style in touched files.

Testing Guidelines

No automated test suite is currently committed.
Required minimum before PR: run verification checklist above on local compose.
For logic-heavy changes, add pytest tests under tests/ and include execution command/results in PR.

Commit & Pull Request Guidelines

Use short, focused commit subjects in imperative tone (existing history: Fix ..., Update ..., Refactor ...).
Keep each commit scoped to one behavior change.
PR must include:
- problem statement and solution summary,
- services/files affected,
- required env/config changes,
- API/log evidence (and UI screenshot if cm_web_view.py changed).

Security & Configuration Tips

Never commit real secrets in .env.
app/cm_bot_hal.py currently contains hardcoded agent credentials/pin; move these to env vars before production use.
Keep container clocks mounted (/etc/timezone, /etc/localtime) as compose currently defines to avoid schedule drift.

4.6 KiB Raw Permalink Blame History