workpod/SPECS.md

# WorkPod 技术规格说明书

> 文档版本：1.0
> 最后更新：2026-03-18
> 项目路径：`E:/workpod`

---

## 1. 概述

### 1.1 项目定位

WorkPod 是一个基于 Docker 的**全栈开发环境容器**，旨在提供统一、可移植、可离线部署的开发环境。

### 1.2 设计目标

| 目标 | 说明 |
|------|------|
| **环境统一** | 消除"在我机器上能跑"的问题 |
| **离线可用** | 所有依赖包本地化，无需网络 |
| **快速启动** | 一键启动完整开发环境 |
| **可迁移性** | 支持导出/导入到服务器 |
| **数据持久化** | 容器可重建，数据不丢失 |

### 1.3 适用场景

- 多工作空间统一开发环境（wk-flux, wk-lab, wk-suke, wk-oth 等）
- 新成员快速上手
- 服务器环境部署
- 离线/内网开发环境

---

## 2. 技术架构

### 2.1 基础架构

```
┌─────────────────────────────────────────────────────────┐
│                    Docker Desktop                        │
│  ┌───────────────────────────────────────────────────┐  │
│  │              workpod 容器 (Ubuntu 22.04)           │  │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐   │  │
│  │  │Python│ │ Node │  │ Go  │ │ Rust │ │MySQL │   │  │
│  │  │ 3.10 │ │ 24.x │ │1.26  │ │1.94  │ │ 8.0  │   │  │
│  │  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘   │  │
│  │  ┌──────┐ ┌──────┐ ┌──────────────────────────┐ │  │
│  │  │Redis │ │ SSH  │ │ Claude Code + OpenClaw   │ │  │
│  │  │ 6.0  │ │ 2222 │ │ (AI 编程工具)             │ │  │
│  │  └──────┘ └──────┘ └──────────────────────────┘ │  │
│  └───────────────────────────────────────────────────┘  │
│         ↕ 数据卷挂载 (/d/docker-data)                    │
│  ┌───────────────────────────────────────────────────┐  │
│  │  MySQL  │  Redis  │  Workspace                    │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

### 2.2 技术栈明细

| 组件 | 版本 | 安装方式 | 启动方式 |
|------|------|---------|---------|
| Ubuntu | 22.04 | 基础镜像 | - |
| Python | 3.10 | apt | 常驻 |
| Node.js | 24.14.0 | 离线包 | 常驻 |
| Go | 1.26.1 | 离线包 | 常驻 |
| Rust | 1.94.0 | 离线包 | 常驻 |
| MySQL | 8.0 | apt | 手动 |
| Redis | 6.0 | apt | 手动 |
| Claude Code | 2.1.78 | 离线包 | 按需 |
| OpenClaw | 2026.3.13 | 离线包 | 按需 |

### 2.3 离线包清单

```
packages/
├── node-v24.14.0-linux-x64.tar.xz      # Node.js 预编译包
├── go1.26.1.linux-amd64.tar.gz         # Go SDK
├── rust-1.94.0-x86_64-unknown-linux-gnu.tar.xz  # Rust 工具链
├── claude-code-2.1.78.tgz              # Claude Code npm 包
├── openclaw-2026.3.13.tgz              # OpenClaw npm 包
└── rustup-init.sh                      # Rust 安装脚本 (备用)
```

---

## 3. 网络配置

### 3.1 端口映射

| 服务 | 宿主机 | 容器 | 协议 | 说明 |
|------|--------|------|------|------|
| SSH | 2222 | 22 | TCP | 远程登录 |
| HTTP | 8080 | 80 | TCP | Web 服务 |
| HTTPS | 8443 | 443 | TCP | 加密 Web 服务 |
| MySQL | 13306 | 3306 | TCP | 数据库 |
| Redis | 16379 | 6379 | TCP | 缓存 |

### 3.2 连接方式

```bash
# SSH 连接
ssh root@localhost -p 2222
# 密码：workpod123

# Docker exec 进入
docker exec -it workpod bash

# 数据库连接
mysql -h 127.0.0.1 -P 13306 -u root
redis-cli -h 127.0.0.1 -p 16379
```

---

## 4. 存储配置

### 4.1 数据卷映射

| 宿主机路径 | 容器路径 | 用途 |
|-----------|---------|------|
| `/d/docker-data/mysql` | `/var/lib/mysql` | MySQL 数据 |
| `/d/docker-data/redis` | `/var/lib/redis` | Redis 数据 |
| `/d/docker-data/workspace` | `/workspace` | 工作目录 |
| `./config/supervisor` | `/etc/supervisor/conf.d` | 进程配置 |

### 4.2 存储要求

| 项目 | 最小空间 | 建议空间 |
|------|---------|---------|
| 镜像构建 | 10 GB | 20 GB |
| 容器运行 | 5 GB | 10 GB |
| MySQL 数据 | 1 GB | 按需 |
| 工作空间 | 1 GB | 按需 |

---

## 5. 构建规范

### 5.1 构建前检查

```bash
# 检查 Docker 状态
docker info
docker ps

# 检查离线包完整性
cd E:/workpod/packages
ls -lh *.tar.* *.tgz
```

### 5.2 构建命令

```bash
# 构建镜像
cd E:/workpod
docker build -t workpod:latest .

# 验证镜像
docker images workpod

# 启动容器
docker-compose up -d

# 验证容器
docker ps --filter name=workpod
```

### 5.3 镜像导出/导入

```bash
# 导出（压缩）
docker save workpod:latest | gzip > workpod.tar.gz

# 导入
docker load < workpod.tar.gz
```

---

## 6. 运维规范

### 6.1 日常操作

```bash
# 启动容器
docker-compose up -d

# 停止容器
docker-compose down

# 重启容器
docker-compose restart

# 查看日志
docker logs -f workpod

# 查看资源使用
docker stats workpod

# 进入容器
docker exec -it workpod bash
```

### 6.2 数据库管理

```bash
# 启动 MySQL
docker exec workpod bash -c "mysqld --user=mysql --datadir=/var/lib/mysql &"

# 启动 Redis
docker exec workpod redis-server --daemonize yes

# 停止 MySQL
docker exec workpod bash -c "mysqladmin -u root shutdown"

# 停止 Redis
docker exec workpod redis-cli shutdown
```

### 6.3 健康检查

```bash
# 检查容器状态
docker inspect workpod --format='{{.State.Health.Status}}'

# 检查 SSH 服务
curl -k https://localhost:2222

# 检查 MySQL
docker exec workpod mysql -e "SELECT VERSION()"

# 检查 Redis
docker exec workpod redis-cli ping
```

---

## 7. 安全规范

### 7.1 访问控制

| 项目 | 当前配置 | 建议 |
|------|---------|------|
| SSH 密码 | workpod123 | 生产环境修改 |
| MySQL root | 无密码 | 生产环境设置密码 |
| Redis | 无密码 | 生产环境设置密码 |

### 7.2 安全加固建议

1. **生产环境**必须修改默认密码
2. 限制端口暴露范围
3. 使用 Docker 网络隔离
4. 定期更新基础镜像

---

## 8. 故障排查

### 8.1 常见问题

| 问题 | 可能原因 | 解决方案 |
|------|---------|---------|
| 容器启动失败 | 端口被占用 | `netstat -ano \| findstr :2222` |
| MySQL 无法启动 | 数据目录权限 | `chown mysql:mysql /var/lib/mysql` |
| SSH 连接失败 | SSH 服务未启动 | `docker exec workpod service ssh start` |
| 构建失败 | 离线包缺失 | 检查 packages/ 目录 |

### 8.2 日志位置

| 日志 | 命令 |
|------|------|
| 容器日志 | `docker logs workpod` |
| SSH 日志 | `docker exec workpod cat /var/log/auth.log` |
| MySQL 日志 | `docker exec workpod cat /var/log/mysql/error.log` |

---

## 9. 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|---------|
| 1.0 | 2026-03-18 | 初始版本 |

---

## 附录 A：快速参考

### A.1 环境信息

```
基础镜像：ubuntu:22.04
时区：Asia/Shanghai
语言：en_US.UTF-8
工作目录：/workspace
```

### A.2 默认账号

| 服务 | 用户名 | 密码 |
|------|-------|------|
| SSH | root | workpod123 |
| MySQL | root | - |
| Redis | - | - |

### A.3 文件位置

```
E:/workpod/
├── Dockerfile           # 镜像构建配置
├── docker-compose.yml   # 容器编排配置
├── entrypoint.sh        # 启动脚本
├── SPECS.md             # 本文档
├── README.md            # 使用说明
├── packages/            # 离线安装包
└── config/supervisor/   # Supervisor 配置
```