# forgefly

**Repository Path**: bovver/forgefly

## Basic Information

- **Project Name**: forgefly
- **Description**: 基于k8s+minio的云编译工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-19
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Forge

Forge is a remote build tool that lets you compile C/C++ projects in a Kubernetes cluster with a local development experience.

## Architecture

```
┌─────────────┐      HTTPS / WebSocket      ┌─────────────┐
│  forge CLI  │  ◄──────────────────────►  │   Gateway   │
│  (local)    │                            │   (K8s)     │
└─────────────┘                            └──────┬──────┘
                                                   │
                          ┌────────────┬───────────┘
                          ▼            ▼
                    ┌─────────┐   ┌─────────┐
                    │  MinIO  │   │ K8s Job │
                    │ (S3)    │   │(Builder)│
                    └─────────┘   └─────────┘
```

## Project Layout

```
.
├── cmd/                    # Application entrypoints
│   ├── forge/              # CLI tool
│   └── gateway/            # Gateway server
├── internal/               # Private application code
│   ├── cli/                # CLI implementation
│   └── gateway/            # Gateway implementation
├── pkg/                    # Public libraries
│   └── api/                # Shared API types
├── deployments/            # Kubernetes manifests & scripts
│   ├── k8s/                # YAML resources
│   └── scripts/            # Deployment helpers
├── docs/                   # Documentation
├── examples/               # Example projects
├── configs/                # Configuration templates
├── ENVIRONMENT_NOTES.md    # 环境问题规避说明
├── Makefile
├── go.mod
└── README.md
```

## Quick Start

### Build

```bash
make build
```

### Run Gateway (local dev)

```bash
export PORT=8080
export K8S_NAMESPACE=forgefly
export MINIO_ENDPOINT=localhost:9000
export FORGE_API_KEYS="demokey:developer"

./build/gateway
```

### Run CLI

```bash
./build/forge build
```

## Environment Issues and Solutions

在开发和部署过程中可能会遇到各种环境问题，项目提供了以下工具和文档来帮助避免和解决这些问题：

### Environment Notes

详细的环境问题规避说明文档位于 [ENVIRONMENT_NOTES.md](ENVIRONMENT_NOTES.md)，包含：

- 网络代理配置（国内镜像加速）
- Podman/Docker 配置问题
- Kubernetes 集群访问
- 镜像构建和推送
- 常见问题排查

### Automatic Environment Fix Tool

项目提供了一个自动环境修复脚本，可以检测和修复常见问题：

```bash
# 交互式修复环境问题
./deployments/scripts/fix-environment.sh

# 自动修复所有问题（不询问确认）
./deployments/scripts/fix-environment.sh --all

# 只检查不修复
./deployments/scripts/fix-environment.sh --dry-run

# 使用自定义镜像仓库
./deployments/scripts/fix-environment.sh --registry 192.168.1.100:5000
```

该脚本会检查：
- 必要工具（Go, Podman, kubectl, make）是否安装
- Podman insecure registry 配置
- 网络代理和 Go 模块代理配置
- 镜像仓库连通性
- Kubernetes 集群连接
- 项目结构完整性

### Updated Deployment Script

Gateway 部署脚本已更新支持 Podman 和新的镜像仓库：

```bash
# 查看部署脚本帮助
./deployments/scripts/deploy-gateway.sh --help

# 完整部署（构建+部署）
./deployments/scripts/deploy-gateway.sh

# 仅构建镜像
./deployments/scripts/deploy-gateway.sh --build-only

# 仅部署
./deployments/scripts/deploy-gateway.sh --deploy-only

# 使用自定义标签
./deployments/scripts/deploy-gateway.sh --tag v2.1.0

# 使用自定义仓库
./deployments/scripts/deploy-gateway.sh --registry 192.168.1.100:5000
```

**主要更新：**
- 使用 Podman 替代 Docker 构建镜像
- 镜像仓库地址更新为 `10.0.0.28:5000`
- 自动检查环境问题
- 更新部署配置文件中的镜像地址

### Makefile Updates

Makefile 已更新支持 Podman：

```bash
# 使用 Podman 构建镜像
make podman-build

# 推送镜像到仓库
make podman-push

# 清理本地镜像
make podman-clean
```

## Documentation

- [Design](docs/design.md) — Architecture and technical design
- [Deployment](docs/deploy.md) — Manual deployment guide
- [Test Plan](docs/test-plan.md)

## License

MIT