memind/docs/goosed-phase1-local-plan.md

# Goosed 本地构建方案 — 第一阶段实施计划

> **阶段目标：** 本地完整验证 Docker 构建方案，无生产影响。  
> **时间预期：** 1–2 周。  
> **关键特点：** 完全本地化，手工构建 + 交付，git.tkmind.cn 代码管理。

---

## 🎯 核心流程

```
Step 1: 代码提交
└─ git push origin main (to git.tkmind.cn)

Step 2: 本地构建
└─ bash scripts/verify-goosed-docker.sh local
   └─ 输出: tkmind/goosed:local 镜像

Step 3: 本地验证 (1–2 周)
├─ docker-compose up -d
├─ 运行测试、监控、性能测试
└─ 确认稳定

Step 4: 镜像交付
├─ docker save goosed.tar
└─ scp 到 103 (后续部署)
```

---

## 📋 你需要的文件（最终清单）

| 文件 | 用途 | 状态 |
|------|-----|------|
| `scripts/verify-goosed-docker.sh` | 本地一键构建 | ✅ 已完成 |
| `docker-compose.local.yml` | 本地开发环境 | ✅ 已完成 |
| `docs/goosed-docker-local-verification.md` | 测试指南 | ✅ 已完成 |
| `docs/goosed-local-build-delivery.md` | 构建 + 交付说明 | ✅ 已完成 |
| `docs/goosed-phase1-local-plan.md` | 本计划 | ✅ 已完成 |

**删除的文件：**
- ❌ `.github/workflows/build-goosed.yml`（GitHub Actions，不需要）
- ❌ `docs/ghcr-setup.md`（ghcr.io，不需要）
- ❌ `docs/goosed-ci-implementation-plan.md`（CI/CD，不需要）

---

## 🚀 立即开始（今天）

### Step 1：提交文件到 git.tkmind.cn

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

# 查看修改
git status

# 添加文件
git add scripts/verify-goosed-docker.sh \
        docker-compose.local.yml \
        docs/goosed-docker-local-verification.md \
        docs/goosed-local-build-delivery.md \
        docs/goosed-phase1-local-plan.md

# 提交
git commit -m "feat: goosed 本地 Docker 构建方案 (第一阶段)

- scripts/verify-goosed-docker.sh: 一键本地构建脚本
- docker-compose.local.yml: 本地开发环境
- docs/goosed-docker-local-verification.md: 本地测试指南
- docs/goosed-local-build-delivery.md: 构建交付方案
- docs/goosed-phase1-local-plan.md: 实施计划

特点：完全本地化，无 CI 依赖，手工构建 + 交付。
时间预期：1-2 周本地验证。"

# 推送到 git.tkmind.cn
git push origin main
```

### Step 2：本地验证（立即运行）

```bash
# 进入项目目录
cd /Users/john/Project/Memind

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

# 预期输出（8–12 分钟）
# ✅ 镜像构建完成
# ✅ 容器已启动
# ✅ 容器已就绪
```

### Step 3：容器测试

```bash
# 脚本会显示测试命令，按提示执行即可
# 例如：

# 查看容器状态
docker ps | grep goosed

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

# 查看日志
docker logs -f <container-id>
```

---

## 📅 一周的验证计划

| 天 | 任务 | 预期 |
|---|-----|-----|
| **Day 1** | 代码提交 + 首次本地构建 | ✅ 镜像构建成功 |
| **Day 2–3** | 单实例运行测试 (18006) | ✅ 容器稳定运行 |
| **Day 4–5** | Docker Compose 双实例测试 | ✅ 两实例无冲突 |
| **Day 6–7** | 长时间运行测试（持续监控） | ✅ 7 天无异常 |

---

## ✅ 本地验证完成标准

以下全部 ✅ 后，认为第一阶段完成：

- [ ] ✅ 代码已提交到 git.tkmind.cn
- [ ] ✅ 本地 Docker 构建成功（无错误）
- [ ] ✅ 镜像大小合理（~50–80MB）
- [ ] ✅ 容器启动正常，`/status` 返回 200
- [ ] ✅ Session 数据库（SQLite）正常创建
- [ ] ✅ 容器日志无 panic / 错误
- [ ] ✅ 两实例并行运行无冲突
- [ ] ✅ 容器重启后数据持久化
- [ ] ✅ 运行至少 7 天无异常
- [ ] ✅ 镜像文件已保存（goosed.tar）

---

## 🔄 持续开发流程

第一阶段期间，如需修改代码：

```bash
# 1. 本地修改代码
# ...your changes...

# 2. 本地测试（如需要重新构建）
bash scripts/verify-goosed-docker.sh local

# 3. 提交代码
git add .
git commit -m "fix: ..."
git push origin main

# 4. 继续本地验证
```

---

## 📦 镜像交付（第一阶段末）

当本地验证通过 1 周后：

### 方式 1：保存为文件（最简单）

```bash
# 保存最新验证通过的镜像
docker save tkmind/goosed:local -o goosed-verified.tar

# 准备交付给 103（后续操作）
ls -lh goosed-verified.tar
# 约 50–80MB
```

### 方式 2：标记版本

```bash
# 给验证通过的镜像打版本标签
docker tag tkmind/goosed:local tkmind/goosed:v1.0-local

# 后续交付时使用 v1.0-local 标记
docker save tkmind/goosed:v1.0-local -o goosed-v1.0.tar
```

---

## ❓ 常见问题

### Q：什么时候推送到 git.tkmind.cn？

**A：** 立即推送。这是代码版本管理，与镜像构建独立。镜像是本地产物，不需要推送到 Git。

### Q：镜像要保存到哪里？

**A：** 本地 Docker 中即可。当需要部署到 103 时，再用 `docker save` 导出为文件。

### Q：如果代码有变更怎么办？

**A：** 
1. 修改代码 → `git push`
2. 重新 `bash scripts/verify-goosed-docker.sh local`
3. 继续测试

### Q：第一阶段需要与 103 通信吗？

**A：** 不需要。完全本地独立。103 部署是后续的第二阶段。

### Q：验证需要多久？

**A：** 建议至少 1 周。如果发现问题，修复后重新计时。

---

## 🛑 何时停止本地验证，考虑 103？

当满足以下条件时：

- ✅ 本地验证稳定运行 7+ 天
- ✅ 所有检查清单项都通过
- ✅ 团队确认 Docker 方案可行
- ✅ 103 环境已准备就绪（Docker daemon）

**不满足上述条件，继续本地验证，不要急着上 103。**

---

## 📞 遇到问题？

参考这些文档：

1. **构建失败？** → `docs/goosed-docker-local-verification.md` 的"常见问题"
2. **交付方式？** → `docs/goosed-local-build-delivery.md` 的"镜像交付"
3. **测试步骤？** → `docs/goosed-docker-local-verification.md` 的"测试与验证"

---

**现在：立即推送代码并运行本地构建！**