> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 本地 PostgreSQL 开发环境

> 使用 Docker Compose 启动本地 PostgreSQL，执行 migration，并以外部状态模式启动 AiOS 控制面。

# 本地 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. 进入仓库根目录

```bash theme={null}
cd /root/code/aios
```

### 2. 启动本地 PostgreSQL

```bash theme={null}
docker compose -f deploy/dev/docker-compose.postgres.yml up -d
docker compose -f deploy/dev/docker-compose.postgres.yml ps
```

如果你想看数据库健康状态：

```bash theme={null}
docker compose -f deploy/dev/docker-compose.postgres.yml logs -f postgres
```

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

```bash theme={null}
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

```bash theme={null}
make migrate-up
```

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

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

```bash theme={null}
go run ./cmd/aios
```

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

```bash theme={null}
curl http://localhost:8080/healthz
curl http://localhost:8080/readyz
curl http://localhost:8080/api/v1/system/info
```

## CLI 示例

```bash theme={null}
# 启动本地 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 资源属于同一组
* 容器健康检查是否已经通过

## 相关页面

* [开始使用](/getting-started/index)
* [第一个 Agent 命令](/getting-started/first-agent-command)
* [配置参考](/platform/config-reference)