memind/docs/goosed-local-build-delivery.md

# Goosed 本地构建与交付方案

> **方案特点：** 完全本地化，no CI/CD 服务器，手工构建 + 手工交付。  
> **适用场景：** 开发验证阶段，103 部署前的完整测试。

## 📊 整体流程

```
代码变更
  ↓
git commit & git push (to git.tkmind.cn)
  ↓
本地手工构建
  ├─ bash scripts/verify-goosed-docker.sh local
  └─ docker image: tkmind/goosed:local
  ↓
本地验证通过 ✅（1–2 周）
  ↓
镜像交付 → 103（两个选项）
  ├─ 选项 A: docker save + scp
  └─ 选项 B: docker push (if Registry)
```

---

## 第一步：环境检查（初次一次性）

### 本地机器准备

```bash
# 1. 检查 Docker 版本
docker --version
# 需要: 20.10+

# 2. 检查 Docker Compose
docker-compose --version
# 需要: 2.0+

# 3. 检查磁盘空间
df -h | grep "/$"
# 需要: 至少 5GB 空闲（Rust 编译会用 2–3GB）

# 4. 测试 Docker 构建
docker build --version
```

### Git 配置确认

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

# 确认 origin 指向 git.tkmind.cn
git remote -v
# origin  git@git.tkmind.cn:tkmind/memind.git (fetch)
# origin  git@git.tkmind.cn:tkmind/memind.git (push)

# 确认分支
git branch -a
```

---

## 第二步：代码变更与提交

### 开发流程

```bash
# 1. 拉取最新代码
git pull origin main

# 2. 本地开发（修改代码、测试等）
# ...your changes...

# 3. 提交到 git.tkmind.cn
git add .
git commit -m "你的变更说明"
git push origin main
```

### 验证提交

```bash
# 检查代码是否已推送到 git.tkmind.cn
git log -1 --oneline  # 查看最新 commit
git push -u origin main  # 确保推送
```

---

## 第三步：本地构建镜像

### 方式 A：使用验证脚本（推荐）

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

# 一键构建 + 启动 + 验证
bash scripts/verify-goosed-docker.sh local

# 脚本会：
# 1. 构建镜像 (8–12 分钟)
# 2. 启动容器
# 3. 等待容器就绪
# 4. 显示测试命令
```

### 方式 B：手工 docker build（更细致控制）

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

# 构建镜像
docker build -f tkmind_go/Dockerfile.goosed \
  -t tkmind/goosed:local \
  tkmind_go/

# 验证镜像
docker images | grep goosed
# tkmind/goosed  local  50MB

# 启动容器
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

# 健康检查
curl http://127.0.0.1:18006/status

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

---

## 第四步：本地验证

### 快速检查

```bash
# 1. 端点是否响应
curl -s http://127.0.0.1:18006/status | jq .

# 2. 容器进程是否运行
docker ps | grep goosed

# 3. 日志是否正常
docker logs goosed-test | tail -20

# 4. 资源使用（应该正常）
docker stats goosed-test
```

### 完整验证（可选但推荐）

```bash
# 1. 启动两个实例（模拟 103 场景）
docker-compose -f docker-compose.local.yml up -d

# 2. 监控资源
docker stats goosed-1 goosed-2

# 3. 测试持久化
docker-compose -f docker-compose.local.yml down -v
docker-compose -f docker-compose.local.yml up -d
# 验证 Session 数据是否保留

# 4. 清理
docker-compose -f docker-compose.local.yml down -v
```

---

## 第五步：镜像交付（供 103 使用）

### 选项 A：保存为文件（适合离线传输）

```bash
# 1. 保存镜像到 tar 文件
docker save tkmind/goosed:local -o goosed.tar

# 2. 检查文件大小
ls -lh goosed.tar
# 大约 50–80MB

# 3. 传输到 103
# 方式 1: 通过 scp
scp goosed.tar john@103:~/incoming/

# 方式 2: 通过 rsync
rsync -av goosed.tar john@103:~/incoming/

# 4. 在 103 上导入（后续操作）
# docker load -i goosed.tar
```

### 选项 B：直接推送（需要 Docker Registry）

如果 103 上有 Docker Registry（Harbor / Local Registry）：

```bash
# 1. 标记镜像
docker tag tkmind/goosed:local registry.tkmind.cn/goosed:v1

# 2. 推送
docker push registry.tkmind.cn/goosed:v1

# 3. 在 103 上拉取
# docker pull registry.tkmind.cn/goosed:v1
```

### 选项 C：使用 Gitea Container Registry（如已启用）

```bash
# 1. 登录 Gitea Registry
# 需要先生成 Gitea token: https://git.tkmind.cn/user/settings/applications

docker login git.tkmind.cn -u your-username -p your-token

# 2. 标记镜像
docker tag tkmind/goosed:local git.tkmind.cn/tkmind/goosed:latest

# 3. 推送
docker push git.tkmind.cn/tkmind/goosed:latest

# 4. 在 103 上拉取
# docker pull git.tkmind.cn/tkmind/goosed:latest
```

---

## 📋 验证检查清单

在认为"本地验证完成"前，确保以下都通过：

- [ ] ✅ Docker 镜像成功构建，无编译错误
- [ ] ✅ 容器启动无异常，`/status` 端点返回 200
- [ ] ✅ Session SQLite 数据库正常创建
- [ ] ✅ 容器日志无 panic / segfault / 错误
- [ ] ✅ 两实例同时运行（18006 + 18007）无冲突
- [ ] ✅ 容器重启后数据持久化（卷挂载正常）
- [ ] ✅ 性能稳定（至少 1 小时无异常）
- [ ] ✅ 镜像文件成功保存或推送

**以上全部通过 = 本地验证完成，可进行 103 部署。**

---

## 常见问题

### Q1：构建失败 - Rust 下载超时

**A:** Rust 镜像下载可能受网络影响。重试或配置代理：

```bash
# 清空缓存重试
docker buildx prune -a
docker build --no-cache -f tkmind_go/Dockerfile.goosed -t tkmind/goosed:local tkmind_go/

# 或使用代理（如有）
docker build --build-arg HTTP_PROXY=http://proxy:8080 \
  -f tkmind_go/Dockerfile.goosed -t tkmind/goosed:local tkmind_go/
```

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

**A:** 查看日志找原因：

```bash
docker logs <container-id>

# 常见原因：
# 1. GOOSE_SERVER__SECRET_KEY 环境变量缺失
# 2. SQLite 权限问题（goose 用户无写权限）
# 3. 数据卷挂载错误
```

### Q3：镜像太大，无法传输

**A:** 可以先在 103 上 pull，或使用增量传输：

```bash
# 压缩传输
docker save tkmind/goosed:local | gzip > goosed.tar.gz

# 传输
scp goosed.tar.gz john@103:~/

# 在 103 上解压导入
gunzip < goosed.tar.gz | docker load
```

### Q4：Session 数据在哪

**A:** 数据存储在 Docker 卷中：

```bash
# 查看卷位置
docker volume inspect goosed-test-data

# 在宿主机上访问
cd /var/lib/docker/volumes/goosed-test-data/_data
ls -la
```

---

## 清理与重置

### 停止容器和卷

```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 rmi tkmind/goosed:local
```

### 完全清理

```bash
# 清理所有 Docker 资源（谨慎）
docker system prune -a --volumes
```

---

## 交付前检查清单

镜像交付给 103 前：

- [ ] ✅ 代码已提交到 git.tkmind.cn
- [ ] ✅ 本地验证通过至少 1 周无异常
- [ ] ✅ 镜像文件已保存或推送
- [ ] ✅ 团队确认 Docker 方案可行
- [ ] ✅ 103 环境已准备（Docker daemon）

**完成上述检查 = 可以考虑 103 部署**

---

## 下一步（103 部署）

当本地验证通过后，计划 103 部署：

1. 在 103 上导入镜像：`docker load -i goosed.tar`
2. 配置运行时环境（端口、卷、Secret）
3. 启动一个容器实例进行灰度测试
4. 监控 24–48 小时，确认稳定
5. 若稳定，逐步增加副本数

**当前阶段：本地验证。** 103 部署是后续的独立议题。