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 连接方式

# 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 构建前检查

# 检查 Docker 状态
docker info
docker ps

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

5.2 构建命令

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

# 验证镜像
docker images workpod

# 启动容器
docker-compose up -d

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

5.3 镜像导出/导入

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

# 导入
docker load < workpod.tar.gz

---

6. 运维规范

6.1 日常操作

# 启动容器
docker-compose up -d

# 停止容器
docker-compose down

# 重启容器
docker-compose restart

# 查看日志
docker logs -f workpod

# 查看资源使用
docker stats workpod

# 进入容器
docker exec -it workpod bash

6.2 数据库管理

# 启动 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 健康检查

# 检查容器状态
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 配置