# AlphaX Agent ｜ Crypto Docker 部署

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

## 重要原则

- Web 默认暴露到宿主机 `8191`，容器内端口 `8190`。
- 运行时数据库是 PostgreSQL，compose 内置 `postgres:16` 服务。
- `DATABASE_URL` 是应用唯一运行时数据库连接入口。
- 当前定位是 CEX 行情机会捕捉，链上采集/API 模块已下线，后续重新规划后再接入。
- 调度器以并发子进程运行，并通过业务锁组避免主推荐写入冲突。
- `.dockerignore` 排除了 `data/`、真实 `.env` 和所有 DB 文件，避免把数据库/密钥打进镜像。

## 快速启动

```bash
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`。

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

常用参数：

```bash
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：

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

访问：

```text
http://127.0.0.1:8191
```

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

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

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

```text
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 默认：

```text
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` 两套库：

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

## SQLite 历史数据导入

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

```bash
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 |
| 复盘 | 86400s |

## 常用验证

```bash
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：

```bash
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'
```

## LLM 解释层配置

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

```bash
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
```

生成缓存解释：

```bash
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 备份：

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

恢复到空库：

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