# 容器名称标准化

**日期**: 2026-01-27  
**类型**: 文档更新  
**影响范围**: 开发文档、脚本

## 变更概述

统一项目中所有 Docker 容器名称引用，修正文档与实际配置不一致的问题。

## 问题背景

项目文档和脚本中使用的容器名称与 `docker-compose.yml` 实际定义不一致：

- 文档中使用：`jointo-server-db`
- 实际名称：`jointo-server-postgres`

这导致脚本执行失败和开发者困惑。

## 变更详情

### 标准容器名称

根据 `server/docker-compose.yml` 配置，项目使用以下容器名称：

| 容器名称 | 服务 | 镜像 | 端口 |
|---------|------|------|------|
| `jointo-server-app` | FastAPI 应用 | 自定义构建 | 6170 |
| `jointo-server-postgres` | PostgreSQL 17 | postgres:17-alpine | 6181 |
| `jointo-server-redis` | Redis 7 | redis:7-alpine | 6183 |
| `jointo-server-minio` | MinIO | minio/minio:latest | 6185, 6187 |
| `jointo-server-adminer` | Adminer | adminer:latest | 6184 |

### 数据库连接信息

- **用户名**: `jointoAI`（非 `postgres`）
- **密码**: `123456`
- **数据库**: `jointo`
- **端口**: 6181（宿主机）→ 5432（容器内）

### 更新的文件

1. **`.kiro/steering/docker-container.md`**
   - 更新容器名称列表
   - 修正示例命令中的容器名和用户名

2. **`.claude/skills/jointo-tech-stack/references/infrastructure.md`**
   - 更新容器名称表格
   - 修正所有 Docker 命令示例
   - 添加 `jointo-server-adminer` 容器

3. **`.claude/skills/jointo-tech-stack/references/migration.md`**
   - 更新备份命令中的容器名和用户名

4. **`server/tests/README.md`**
   - 更新测试环境设置命令
   - 修正故障排查命令

5. **`server/migrate_db.sh`**
   - 修正 `DB_CONTAINER` 变量值

## 标准命令示例

### 数据库操作

```bash
# 进入数据库容器
docker exec -it jointo-server-postgres bash

# 执行 SQL 查询
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "SELECT 1"

# 备份数据库
docker exec jointo-server-postgres pg_dump -U jointoAI -d jointo > backup.sql

# 恢复数据库
docker exec -i jointo-server-postgres psql -U jointoAI -d jointo < backup.sql
```

### 迁移操作

```bash
# 执行迁移
docker exec jointo-server-app alembic upgrade head

# 查看迁移状态
docker exec jointo-server-app alembic current

# 创建新迁移
docker exec jointo-server-app alembic revision --autogenerate -m "描述"
```

### 服务管理

```bash
# 启动所有服务
docker compose up -d

# 启动特定服务
docker compose up -d jointo-server-postgres jointo-server-redis

# 重启服务
docker restart jointo-server-app
docker restart jointo-server-postgres

# 查看日志
docker logs jointo-server-app
docker logs jointo-server-postgres
```

## 影响评估

### 开发者影响

- ✅ **无破坏性变更**：仅更新文档和脚本
- ✅ **提高一致性**：文档与实际配置保持一致
- ✅ **减少错误**：避免因容器名错误导致的命令失败

### 需要注意

⚠️ **数据库用户名**：使用 `jointoAI` 而非 `postgres`

⚠️ **容器名称**：使用 `jointo-server-postgres` 而非 `jointo-server-db`

⚠️ **端口映射**：宿主机端口与容器内端口不同

## 验证步骤

```bash
# 1. 检查所有容器运行状态
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 2. 验证数据库连接
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "SELECT version();"

# 3. 验证迁移脚本
cd server && ./migrate_db.sh current

# 4. 验证 Redis 连接
docker exec jointo-server-redis redis-cli ping

# 5. 验证 MinIO 访问
curl http://localhost:6185/minio/health/live
```

## 相关文档

- [Docker 容器化规范](.kiro/steering/docker-container.md)
- [基础设施配置](.claude/skills/jointo-tech-stack/references/infrastructure.md)
- [迁移系统规范](.claude/skills/jointo-tech-stack/references/migration.md)
- [测试指南](../../server/tests/README.md)

## 后续建议

1. ✅ 统一容器名称引用
2. ⏳ 考虑在 CI/CD 中添加容器名称验证
3. ⏳ 定期检查文档与配置的一致性