alphax/README_DOCKER.md

AlphaX Agent ｜ Crypto Docker 部署

这是 AlphaX Agent ｜ Crypto 的 Docker 化运行目录。当前运行时数据库已经一次性切换为 PostgreSQL；SQLite 只作为历史数据导入来源，不再作为应用运行时数据库。

重要原则

• Web 默认暴露到宿主机 8191，容器内端口 8190。
• 运行时数据库是 PostgreSQL，compose 内置 postgres:16 服务。
• DATABASE_URL 是应用唯一运行时数据库连接入口。
• 链上主数据源是 NodeReal，只采集 Ethereum / BSC；.env 中配置 ALPHAX_NODEREAL_API_KEY 后，python -m app.cli onchain 才会产出链上事件。
• NodeReal 原始 Transfer 会先进入 onchain_raw_events 展示，再自动读取 ERC-20 metadata 尝试映射交易所 XXX/USDT；ALPHAX_ONCHAIN_TOKEN_MAPPINGS 只作为人工兜底。
• 调度器以并发子进程运行，并通过业务锁组避免主推荐写入冲突。
• .dockerignore 排除了 data/、真实 .env 和所有 DB 文件，避免把数据库/密钥打进镜像。

快速启动

cp .env.example .env
# 按需编辑 .env 中的 POSTGRES_* / DATABASE_URL / 推送 / LLM / 链上 API key

docker compose build
docker compose up -d postgres alphax-web alphax-scheduler

一键更新已部署服务器

仓库提供 scripts/deploy_server.sh，用于更新一台已经部署过 AlphaX 的服务器。它不会做全新初始化，只会把本地提交推到远端，然后 SSH 到服务器现有项目目录执行 git pull --ff-only、docker compose build 和 docker compose up -d。

DEPLOY_HOST="user@your-server" \
REMOTE_DIR="/srv/alphax-docker" \
DEPLOY_MESSAGE="deploy: update alphax" \
bash scripts/deploy_server.sh

常用参数：

DEPLOY_BRANCH=main
DEPLOY_SERVICES="alphax-web alphax-scheduler alphax-price-streamer"
DEPLOY_RUN_MIGRATIONS=1
DEPLOY_HEALTHCHECK_URL="http://127.0.0.1:8191/api/stats"
DEPLOY_SKIP_COMMIT=1
DEPLOY_SKIP_PUSH=1
DEPLOY_SKIP_BUILD=1

注意：如果本地有未提交改动，脚本会要求提供 DEPLOY_MESSAGE 后才自动 git add -A && git commit；避免无意识把半成品部署到线上。

如果代码已经提交并推送过，只想让服务器拉最新代码并重启，可以跳过本地提交和 push：

DEPLOY_HOST="user@your-server" \
REMOTE_DIR="/srv/alphax-docker" \
DEPLOY_SKIP_COMMIT=1 \
DEPLOY_SKIP_PUSH=1 \
bash scripts/deploy_server.sh

访问：

http://127.0.0.1:8191

首次空库启动时会自动创建默认管理员账号：

邮箱：admin@alphax.local
密码：AlphaXAdmin123

建议首次登录后立刻修改密码。也可以在 .env 中覆盖：

ALPHAX_BOOTSTRAP_ADMIN=1
ALPHAX_DEFAULT_ADMIN_EMAIL=your-admin@example.com
ALPHAX_DEFAULT_ADMIN_PASSWORD=change-me-to-a-strong-password

该初始化只会在 app_user 表为空时执行；迁移旧数据后不会覆盖已有账号。

数据库配置

本地 dev 默认：

POSTGRES_DB=alphax_dev
POSTGRES_USER=alphax
POSTGRES_PASSWORD=alphax_dev_password
DATABASE_URL=postgresql://alphax:alphax_dev_password@postgres:5432/alphax_dev
ALPHAX_DB_BACKEND=postgres

生产环境建议只区分 dev 和 production 两套库：

ALPHAX_ENV=production
DATABASE_URL=postgresql://<user>:<password>@<host>:5432/<database>

SQLite 历史数据导入

SQLite 不再用于运行时。如果需要把旧 altcoin_monitor.db / scheduler_state.db 导入 PostgreSQL，先启动 PostgreSQL，再运行：

docker compose up -d postgres
docker compose run --rm alphax-web python scripts/postgres/run_migrations.py
docker compose run --rm alphax-web python scripts/postgres/import_from_sqlite.py \
  --sqlite-path /app/data/altcoin_monitor.db \
  --scheduler-sqlite-path /app/data/scheduler_state.db
docker compose run --rm alphax-web python scripts/postgres/validate_import.py \
  --sqlite-path /app/data/altcoin_monitor.db \
  --scheduler-sqlite-path /app/data/scheduler_state.db \
  --all-tables

导入完成后，应用运行只读写 PostgreSQL。

服务说明

• postgres：PostgreSQL 16，数据保存在 compose volume postgres_data。
• alphax-web：FastAPI + 静态页面。
• alphax-scheduler：调度器，读取 PostgreSQL 中的任务配置和运行状态。

默认任务周期：

任务	间隔
事件舆情	60s
价格跟踪	180s
爆发确认	600s
粗筛/细筛	900s
舆情采集	1800s
LLM 舆情分析	1800s
链上追踪	1800s
复盘	86400s

常用验证

python3 scripts/validate_docker_layout.py
docker compose config
docker compose ps
docker compose logs --tail=100 alphax-web
docker compose logs --tail=100 alphax-scheduler

容器内 API smoke：

docker compose exec alphax-web curl -fsS http://127.0.0.1:8190/api/stats
docker compose exec alphax-web curl -fsS 'http://127.0.0.1:8190/api/pipeline/runs?page=1&page_size=5'
docker compose exec alphax-web curl -fsS http://127.0.0.1:8190/api/onchain/overview

LLM 解释层配置

LLM 是运行时系统能力，不属于策略参数，不写入 rules.yaml。在 .env 中配置：

ALPHAX_LLM_ENABLED=1
ALPHAX_LLM_BASE_URL=https://api.openai.com/v1
ALPHAX_LLM_API_KEY=your-key
ALPHAX_LLM_MODEL=gpt-4o-mini

生成缓存解释：

docker compose exec alphax-web python -m app.cli llm-insights --scope recommendations --limit 30
docker compose exec alphax-web python -m app.cli llm-insights --scope sentiment --limit 30
docker compose exec alphax-web python -m app.cli llm-insights --scope review --limit 10

备份与恢复

PostgreSQL 备份：

docker compose exec postgres pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" > alphax_backup.sql

恢复到空库：

cat alphax_backup.sql | docker compose exec -T postgres psql -U "$POSTGRES_USER" "$POSTGRES_DB"