Docker Compose 运维指引

./dev            # = setup（创建 .env.docker.local）+ 构建并启动全栈 + 健康自检 + doctor

# 1. 复制模板
cp .env.docker .env.docker.local

# 2. 编辑 .env.docker.local，填写所需密钥（文件已被 .gitignore 忽略）

# 指定版本拉取并启动（跳过本地构建）
NEGENTROPY_IMAGE_TAG=1.2.0 docker compose pull
NEGENTROPY_IMAGE_TAG=1.2.0 docker compose up -d --no-build

# 1. 拉取新版本镜像
NEGENTROPY_IMAGE_TAG=1.3.0 docker compose pull

# 2. 重建并启动（仅重建镜像变更的容器）
NEGENTROPY_IMAGE_TAG=1.3.0 docker compose up -d --no-build

# 构建所有镜像并启动
docker compose up -d

# 仅构建不启动
docker compose build

# 无缓存全量重建
docker compose build --no-cache

# 修改源码后重建 backend
docker compose build backend && docker compose up -d backend

docker compose up -d                    # 后台启动所有服务
docker compose down                     # 停止并移除容器（保留数据卷）
docker compose down -v                  # 停止并移除容器和数据卷（⚠ 数据不可恢复）
docker compose restart <service>        # 重启单个服务
docker compose stop                     # 暂停所有服务（不移除容器）
docker compose start                    # 恢复已暂停的服务

# 查看所有服务状态（含健康检查结果）
docker compose ps

# 预期输出示例：
# NAME                    STATUS
# negentropy-backend      Up 2 minutes (healthy)
# negentropy-perceives    Up 3 minutes (healthy)
# negentropy-postgres     Up 3 minutes (healthy)
# negentropy-ui           Up 90 seconds (healthy)
# negentropy-wiki         Up 60 seconds (healthy)

# 查询单个容器健康状态
docker inspect --format='{{.State.Health.Status}}' negentropy-backend
# 预期输出: healthy

# 查看健康检查历史（排查启动失败原因）
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' negentropy-backend

docker compose logs -f                  # 跟踪所有服务日志
docker compose logs -f backend          # 跟踪 backend 日志
docker compose logs --since 30m perceives  # 最近 30 分钟 perceives 日志
docker compose logs --tail 100 ui       # ui 最近 100 行日志

# 查看卷信息
docker volume ls | grep postgres_data
docker volume inspect damascus-v3_postgres_data

# 备份数据库
docker compose exec postgres pg_dump -U aigc negentropy > backup_$(date +%Y%m%d).sql

# 恢复数据库
cat backup_20260612.sql | docker compose exec -T postgres psql -U aigc negentropy

# 直连 PostgreSQL
docker compose exec postgres psql -U aigc -d negentropy

# 构建全部 4 个自建镜像
docker compose build

# 仅构建单个服务
docker compose build backend

# 无缓存全量重建（Dockerfile 或依赖变更后）
docker compose build --no-cache perceives

# 构建并启动（镜像变更时自动重建）
docker compose up -d --build

# 删除未使用的镜像、容器、网络
docker system prune

# 全面清理（含所有未使用镜像和卷，谨慎使用）
docker system prune -a --volumes

# 仅清理构建缓存
docker builder prune

# 查看磁盘占用
docker system df

# 查看合并后的 Compose 配置（验证环境变量是否正确注入）
docker compose config

# 进入运行中的容器
docker compose exec backend bash

# 直连 PostgreSQL（执行 SQL 查询）
docker compose exec postgres psql -U aigc -d negentropy

# 查看容器内进程
docker compose top

# 查看容器资源占用
docker stats --no-stream

# 检查镜像多架构信息
docker buildx imagetools inspect threefishai/negentropy-backend:latest

# 仓内无历史发布 tag（预期为空）
git tag --list 'negentropy-v*'

# Docker Hub 上镜像仓库不存在（HTTP 404 即从未发布）
curl -s -o /dev/null -w '%{http_code}\n' https://hub.docker.com/v2/repositories/threefishai/negentropy-backend/tags/

export NEGENTROPY_IMAGE_TAG=0.0.1
docker compose -f docker-compose.yml up -d --no-build
curl -fsS http://localhost:3292/health                               # backend 健康（HTTP 200）
docker compose -f docker-compose.yml exec backend negentropy doctor  # 应用自检（含 DB / pgvector 扩展）

# 推送 prerelease tag
git tag negentropy-v0.0.1-rc.1
git push origin negentropy-v0.0.1-rc.1

docker buildx imagetools inspect threefishai/negentropy-backend:0.0.1-rc.1
# 预期输出含 linux/amd64 和 linux/arm64 两个 platform

# 推送 stable tag
git tag negentropy-v1.2.0
git push origin negentropy-v1.2.0

# 1. 确认镜像多架构完整性
docker buildx imagetools inspect threefishai/negentropy-backend:1.2.0

# 2. 在全新主机上验证部署
NEGENTROPY_IMAGE_TAG=0.0.1-rc.1 docker compose pull
NEGENTROPY_IMAGE_TAG=0.0.1-rc.1 docker compose up -d --no-build

# 3. 等待所有服务 healthy
docker compose ps

# 4. 功能验证：访问 http://localhost:3192 (UI) 和 http://localhost:3092 (Wiki)

# 1. 指定历史版本拉取并启动
NEGENTROPY_IMAGE_TAG=<previous-version> docker compose pull
NEGENTROPY_IMAGE_TAG=<previous-version> docker compose up -d --no-build

# 2. 确认回滚成功
docker compose ps