跳转到主要内容

​
本地 PostgreSQL 开发环境

​
适用对象

本页面适用于需要在本机以“状态外置”方式开发和调试 AiOS 控制面的维护者与开发者。

​
目标与范围

本页说明如何：
  1. 用仓库内提供的 Docker Compose 启动本地 PostgreSQL
  2. 为当前 schema 执行 migration
  3. 让 go run ./cmd/aios 走 PostgreSQL-backed 模块装配，而不是进程内 stub

​
核心概念

  • 当前仓库的正式外部状态存储路径是 PostgreSQL，不是 SQLite
  • cmd/aios 在 dev 运行模式下也要求 postgres.dsn，不会再静默回退到内存仓储
  • Makefile 的 migrate-up / migrate-down 依赖 golang-migrate 的 migrate 命令

​
标准流程

​
1. 进入仓库根目录

cd /root/code/aios

​
2. 启动本地 PostgreSQL

docker compose -f deploy/dev/docker-compose.postgres.yml up -d
docker compose -f deploy/dev/docker-compose.postgres.yml ps
如果你想看数据库健康状态： 
docker compose -f deploy/dev/docker-compose.postgres.yml logs -f postgres

​
3. 配置 AiOS 运行时环境变量

export AIOS_RUNTIME__MODE=dev
export AIOS_DEV_COMPOSE_PROJECT=aios-dev
export AIOS_DEV_POSTGRES_PORT=5432
export AIOS_POSTGRES__DSN="postgres://aios:aios@localhost:${AIOS_DEV_POSTGRES_PORT}/aios?sslmode=disable"
export DATABASE_URL="$AIOS_POSTGRES__DSN"
说明：
  • AIOS_RUNTIME__MODE=dev 保持当前本地开发语义
  • dev 模式现在要求 PostgreSQL 可用；只有 bootstrap 模式允许无 DSN 启动
  • AIOS_DEV_COMPOSE_PROJECT 用于隔离不同工作树或不同开发者的 Compose 资源名
  • AIOS_DEV_POSTGRES_PORT 用于避开本机已有的 5432
  • AIOS_POSTGRES__DSN 会覆盖 postgres.dsn
  • DATABASE_URL 供 migration 命令使用

​
4. 执行 migration

make migrate-up
如果你的环境里还没有 migrate 命令，需要先安装 golang-migrate，因为当前 Makefile 直接调用它。

​
5. 启动当前 server/bootstrap 入口

go run ./cmd/aios

​
6. 验证服务已连到外部状态存储

curl http://localhost:8080/healthz
curl http://localhost:8080/readyz
curl http://localhost:8080/api/v1/system/info

​
CLI 示例

# 启动本地 PostgreSQL
docker compose -f deploy/dev/docker-compose.postgres.yml up -d

# 执行 migration
export AIOS_RUNTIME__MODE=dev
export AIOS_DEV_COMPOSE_PROJECT=aios-dev
export AIOS_DEV_POSTGRES_PORT=5432
export AIOS_POSTGRES__DSN="postgres://aios:aios@localhost:${AIOS_DEV_POSTGRES_PORT}/aios?sslmode=disable"
export DATABASE_URL="$AIOS_POSTGRES__DSN"
make migrate-up

# 启动控制面
go run ./cmd/aios

# 关闭本地 PostgreSQL
docker compose -f deploy/dev/docker-compose.postgres.yml down

​
Web UI 路径

本页面面向本地控制面开发，不对应固定业务 UI 页面。服务启动后可再访问 Web 前端或直接调用已冻结的 HTTP API。

​
常见问题 / 风险提示

​
1. 只启动 go run ./cmd/aios，没有配置 DSN

这种情况下 dev 模式会直接启动失败。当前只有 bootstrap 模式允许无 DSN 启动，而那条路径仍然只是临时 stub，不适合作为“状态外置”的开发闭环。

​
2. make migrate-up 报 migrate: command not found

说明本机没有安装 golang-migrate CLI。先补齐该工具，再执行 migration。

​
3. PostgreSQL 已启动但应用仍报连接失败

请核对：
  • AIOS_POSTGRES__DSN
  • AIOS_DEV_POSTGRES_PORT 与 DSN 里的端口是否一致
  • AIOS_DEV_COMPOSE_PROJECT 是否和你预期的容器/volume 资源属于同一组
  • 容器健康检查是否已经通过

​
相关页面