memind/docs/goosed-docker-local-verification.md

# Goosed Docker 本地验证指南

> **目标：** 在本地完全验证 goosed Docker 镜像构建、运行、性能，然后再部署到 103。  
> **方案：** 完全本地化（git.tkmind.cn + 本地 Docker + 手工交付）。  
> **时间预期：** 1–2 周本地验证。

## 🚀 快速开始（5 分钟）

### 一键本地构建 + 验证

```bash
cd /Users/john/Project/Memind

# 本地构建镜像 + 启动容器 + 健康检查
bash scripts/verify-goosed-docker.sh local
```

脚本执行流程：
1. 构建 `tkmind/goosed:local` Docker 镜像
2. 启动容器到 18006 端口
3. 等待 `/status` 端点就绪（最多 30 秒）
4. 显示容器日志和可用的测试命令
5. 容器保持运行供手工测试

---

## 详细步骤

### 第一次构建（15 分钟）

#### 1. 检查环境

```bash
# Docker 版本（需 20.10+）
docker --version

# Docker Compose（需 2.0+）
docker-compose --version

# 检查磁盘空间（Rust 编译需 ~2GB）
docker system df
```

#### 2. 本地构建镜像

```bash
cd /Users/john/Project/Memind

# 方式 A：直接从 Dockerfile 构建（首次较慢）
docker build -f tkmind_go/Dockerfile.goosed -t tkmind/goosed:local tkmind_go/

# 方式 B：使用 Docker Buildx 缓存加速（推荐）
docker buildx build \
  -f tkmind_go/Dockerfile.goosed \
  -t tkmind/goosed:local \
  --load \
  tkmind_go/
```

预期：**8–12 分钟**（首次较慢，后续有缓存）

输出示例：
```
=> exporting to docker image format                                 0.3s
=> => exporting layers                                              0.2s
=> => exporting manifest sha256:abc123...                           0.0s
=> => exporting config sha256:def456...                             0.0s
Successfully tagged tkmind/goosed:local
```

#### 3. 验证镜像

```bash
# 查看镜像大小
docker images | grep goosed
# tkmind/goosed  local  sha256:abc123  50MB

# 检查镜像层
docker history tkmind/goosed:local
```

---

### 第二步：启动 & 测试

#### 方式 A：脚本（推荐）

```bash
bash scripts/verify-goosed-docker.sh local

# 输出应该显示：
# ✅ 镜像构建完成
# ✅ 容器已启动
# ✅ 容器已就绪
```

#### 方式 B：手工 docker run

```bash
docker run -d --name goosed-test \
  -p 18006:18006 \
  -e GOOSE_HOST=0.0.0.0 \
  -e GOOSE_PORT=18006 \
  -e GOOSE_SERVER__SECRET_KEY=test-secret \
  -v goosed-test-data:/home/goose/.local/share/goose \
  tkmind/goosed:local
```

#### 方式 C：Docker Compose（两个实例）

```bash
# 启动两个 goosed 实例（18006 + 18007）
docker-compose -f docker-compose.local.yml up -d

# 查看状态
docker-compose -f docker-compose.local.yml ps

# 查看日志
docker-compose -f docker-compose.local.yml logs -f goosed-1
```

---

## 测试与验证

### 1. 健康检查

```bash
# 检查 /status 端点
curl http://127.0.0.1:18006/status

# 预期响应（JSON）：
# {"status": "ok", "version": "..."}
```

### 2. 容器日志

```bash
# 查看完整日志（最后 50 行）
docker logs goosed-test | tail -50

# 持续流式日志
docker logs -f goosed-test

# 搜索错误
docker logs goosed-test 2>&1 | grep -i error
```

### 3. 容器内部检查

```bash
# 进入容器 shell
docker exec -it goosed-test /bin/bash

# 在容器内检查
cd /home/goose/.local/share/goose
ls -la
file goose.db  # Session 数据库

# 检查网络
netstat -tlnp | grep 18006

# 退出容器
exit
```

### 4. 资源使用

```bash
# 监控资源使用（CPU、内存）
docker stats goosed-test

# 预期：
# CPU ~5–20%（空闲时）
# MEM 100–300MB（依赖 session 规模）
```

### 5. 性能测试（可选）

```bash
# 如果有测试工具，可以测试并发连接
# 示例：使用 Apache Bench（需安装 ab）
ab -n 100 -c 10 http://127.0.0.1:18006/status

# 或使用 wrk（需安装）
wrk -t4 -c100 -d10s http://127.0.0.1:18006/status
```

---

## 与 103 对接前的检查清单

在考虑部署到 103 前，在本地完成以下检查：

- [ ] ✅ 镜像构建成功，无编译错误
- [ ] ✅ 容器启动无异常，`/status` 端点响应正常
- [ ] ✅ Session 数据库（SQLite）正常创建和存储
- [ ] ✅ 容器日志无 panic / segfault / 权限错误
- [ ] ✅ 两个实例可同时运行（18006 + 18007），无端口冲突
- [ ] ✅ Docker 卷挂载正常，数据持久化工作
- [ ] ✅ 容器重启后数据不丢失
- [ ] ✅ 与本地 Portal (server.mjs) 集成测试通过（可选，需代理配置）

完成上述检查后，记录以下信息供 103 部署参考：

```markdown
## 镜像交付信息

- **镜像名称：** ghcr.io/your-org/memind/goosed:latest
- **镜像大小：** ~50MB
- **运行用户：** goose (UID 1000)
- **开放端口：** 18006
- **数据目录：** /home/goose/.local/share/goose
- **所需环境变量：** GOOSE_SERVER__SECRET_KEY（必填）
- **健康检查：** GET http://127.0.0.1:18006/status
```

---

## 常见问题

### Q1：构建失败 - "cargo not found"

**A:** Dockerfile 内部会安装 Rust，不需要本地 cargo。如果失败，检查：

```bash
# 清空 Docker 构建缓存
docker buildx prune -a

# 重新构建
docker build --no-cache -f tkmind_go/Dockerfile.goosed -t tkmind/goosed:local tkmind_go/
```

### Q2：容器启动后立即退出

**A:** 查看日志获得错误信息：

```bash
docker logs <container-id>

# 常见原因：
# 1. GOOSE_SERVER__SECRET_KEY 缺失
# 2. 数据卷权限不足（goose 用户无写权限）
# 3. SQLite 数据库损坏
```

### Q3：容器内 /status 返回 404

**A:** goosed 服务可能未就绪或崩溃：

```bash
# 检查进程
docker exec goosed-test ps aux | grep goosed

# 检查监听端口
docker exec goosed-test netstat -tlnp

# 查看完整日志
docker logs goosed-test
```

### Q4：Session 数据在哪里？

**A:** SQLite 数据库位置：

```bash
# 卷挂载位置（宿主机）
docker volume inspect goosed-test-data
# 查看 "Mountpoint" 字段

# 容器内路径
docker exec goosed-test ls -la /home/goose/.local/share/goose/
```

---

## 清理

```bash
# 停止单个容器
docker stop goosed-test
docker rm goosed-test
docker volume rm goosed-test-data

# 或使用 Compose
docker-compose -f docker-compose.local.yml down -v

# 清理所有本地镜像/容器（谨慎！）
docker system prune -a
```

---

## 下一步（不在本阶段执行）

一旦本地验证通过，部署到 103 时需要：

1. 203 上安装 Docker / Podman
2. 配置镜像仓库凭证（ghcr.io pull token）
3. 编写 systemd 服务或 compose 文件（103 端）
4. Session 存储迁移计划（SQLite → PostgreSQL，参考 `goose-session-postgres-migration.md`）
5. 回滚方案（若有问题快速降级）

**当前阶段：仅本地验证。**