# agent-devops

**Repository Path**: xiaohan2013/agent-devops

## Basic Information

- **Project Name**: agent-devops
- **Description**: 智能化运维
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent DevOps

> AI Agent 工具集 + DevOps 实践  
> 跨平台（Windows / macOS / Linux）

---

## 📋 项目概述

本仓库包含两类内容：

### Skills（技能模板）

| Skill | 说明 |
|-------|------|
| [`nodejs/init-node`](nodejs/init-node/) | 初始化 Node.js 开发环境（nvm + Node LTS + pnpm，支持中国镜像） |
| [`python/init-fastpi-full-stack`](python/init-fastpi-full-stack/) | 初始化 FastAPI 全栈项目（SQLite/PostgreSQL、微信小程序 + Web 前端、loguru 日志、编码规范） |

### GitLab CI/CD Demo

基于 Docker Compose 的一键式 GitLab CI/CD 本地部署方案：

- **GitLab CE** — 代码托管 + CI/CD 引擎
- **GitLab Runner** — 流水线执行器（Docker executor）
- **CI/CD 流水线** — 代码分析 → 测试 → 构建 → 部署全链路
- **示例应用** — Node.js 演示项目，开箱即验证

---

## 🏗️ 系统架构

```
┌──────────────────────────────────────────────────┐
│                    Docker Host                     │
│  ┌─────────────────┐     ┌──────────────────────┐ │
│  │   GitLab CE      │     │   GitLab Runner       │ │
│  │   (CE 17.11.1)   │◄────│   (Docker Executor)   │ │
│  │                  │     │                      │ │
│  │  Port: 80/443    │     │  Tags: gitlab-duo,   │ │
│  │  SSH: 2222       │     │        agentic,docker│ │
│  └────────┬─────────┘     └──────────┬───────────┘ │
│           │                          │              │
│           └──────gitlab-net──────────┘              │
└──────────────────────────────────────────────────┘
```

---

## ✅ 前置条件

| 组件 | 最低要求 | 说明 |
|------|---------|------|
| Docker Engine | 24+ | [安装指南](https://docs.docker.com/engine/install/) |
| Docker Compose | V2+（内置） | Docker Desktop 或 docker-compose-plugin |
| 内存 | 4 GB+ | GitLab CE 建议 4GB，2GB 以下可能启动失败 |
| 磁盘 | 10 GB+ 可用 | 镜像 ~2.5GB + 运行时数据 |
| 网络 | 宽带连接 | 首次部署需拉取 ~2.5GB 镜像 |

> **首次部署提示**：GitLab CE 镜像约 2.5GB，拉取耗时取决于网络速度（通常 15~45 分钟）。  
> 建议先执行 `docker pull gitlab/gitlab-ce:17.11.1-ce.0` 预拉取。

---

## 🚀 快速开始

### 一键部署

根据你的操作系统选择对应的部署脚本：

```bash
# Linux / macOS
cd gitlab && bash deploy.sh

# Windows (PowerShell)
cd gitlab && .\deploy.ps1

# Windows (CMD)
cd gitlab && deploy.cmd
```

### 分步部署

```bash
# 1. 创建数据目录
mkdir -p gitlab/runtime/gitlab/{config,logs,data}
mkdir -p gitlab/runtime/gitlab-runner/config

# 2. 创建环境变量文件
cp gitlab/.env.example gitlab/.env

# 3. 启动 GitLab
docker compose -f gitlab/docker-compose.yml up -d gitlab

# 4. 等待就绪（约 3~5 分钟）
docker inspect -f '{{.State.Health.Status}}' gitlab
# 输出 "healthy" 即可继续

# 5. 获取 Runner Token
docker exec -i gitlab bash -c 'cat /etc/gitlab/runner_registration_token'

# 6. 写入 .env
echo "RUNNER_TOKEN=<上一步获取的 Token>" > gitlab/.env

# 7. 启动 Runner
docker compose -f gitlab/docker-compose.yml up -d gitlab-runner

# 8. 获取 root 初始密码
docker exec gitlab cat /etc/gitlab/initial_root_password
```

---

## 📁 项目结构

```
.
├── README.md                          # 本文件
├── python/                            # Python 技能模板
│   └── init-fastpi-full-stack/        # FastAPI 全栈项目脚手架
│       ├── SKILL.md                   # 技能入口
│       ├── scripts/scaffold.py        # 跨平台生成脚本（argparse）
│       ├── references/                # 参考文档（01-09）
│       └── assets/                    # 静态资源
├── nodejs/                            # Node.js 技能模板
│   └── init-node/                     # Node.js 环境初始化
│       └── SKILL.md
├── gitlab/                            # GitLab CI/CD 部署配置
│   ├── docker-compose.yml
│   ├── .env.example
│   ├── .gitlab-ci.yml
│   ├── deploy.sh / deploy.ps1 / deploy.cmd
│   └── runtime/                       # 持久化数据（gitignore）
├── gitlab_src/                        # 示例 Node.js 应用
├── bugs/                              # 测试缺陷报告
└── .reasonix/                         # 工具配置（忽略）
```

---

## 🐍 init-fastpi-full-stack

快速初始化一个生产级 FastAPI 全栈项目。

### 特性

| 层级 | 技术栈 |
|------|--------|
| 框架 | FastAPI + Uvicorn |
| 数据库 | SQLAlchemy 2.0 async + SQLite（本地）/ PostgreSQL（生产）+ Alembic |
| 认证 | JWT (python-jose) + bcrypt (passlib) |
| 日志 | loguru（后端）+ 结构化 console logger（前端） |
| 前端 | Web SPA（vanilla HTML/JS）+ 微信小程序 |
| 测试 | pytest + pytest-asyncio + httpx |
| 规范 | Ruff strict + mypy + pre-commit（6 hooks）+ .editorconfig + Makefile |

### 使用

```bash
# 本地开发（SQLite + 前端，默认）
python python/init-fastpi-full-stack/scripts/scaffold.py my-project

# 生产环境（PostgreSQL + Docker）
python python/init-fastpi-full-stack/scripts/scaffold.py my-project --db postgres

# 仅后端
python python/init-fastpi-full-stack/scripts/scaffold.py my-project --frontend none
```

Windows 用户可使用自动生成的 `scaffold.bat` 或 `scaffold.ps1`。

### 作为 OpenCode Skill 安装（项目级）

将 `init-fastpi-full-stack` 安装为 OpenCode 项目级技能，供 AI Coding Agent 自动识别和调用。

#### 安装步骤

```bash
# 1. 在你的项目根目录下创建 Skill 目录
mkdir -p .opencode/skills/fastpi-fullstack

# 2. 从本仓库拷贝技能文件（根据实际路径调整）
cp -r python/init-fastpi-full-stack/* .opencode/skills/fastpi-fullstack/
```

#### 安装后目录结构

```
.opencode/skills/fastpi-fullstack/
├── SKILL.md                          ← 技能主定义
├── assets/.gitkeep                   ← 资源占位
├── references/                       ← 参考规范文档（10 份）
│   ├── 01-project-config.md
│   ├── 02-app-core.md
│   ├── ...
│   └── 10-ai-agents.md              ← AI Agent 指令文件
└── scripts/                          ← 脚手架脚本（跨平台）
    ├── scaffold.py
    ├── scaffold.bat
    └── scaffold.ps1
```

#### 使用方式

1. 重启 OpenCode（加载新技能）
2. 在项目目录下进入 OpenCode 会话
3. 发送指令：`使用 fastpi-fullstack 技能，初始化一个标准 FastAPI 全栈项目`

---

## 🔄 CI/CD 流水线

流水线定义在 [`.gitlab-ci.yml`](gitlab/.gitlab-ci.yml)，包含四个阶段：

| 阶段 | Job 名称 | 执行内容 | 触发条件 |
|------|---------|---------|---------|
| 🕵️ **code_analyze** | `code-analysis` | `npm ci` → `npm run lint` → `tsc --noEmit` | `gitlab_src/**/*` 变更 |
| 🧪 **test** | `unit-test` | `npm ci` → `npm test` | `gitlab_src/**/*` 变更 |
| 📦 **build** | `build-image` | `docker build` → 保存镜像产物 | `gitlab_src/**/*` 变更 |
| 🚀 **deploy** | `deploy-dev` | 推送至开发环境 | `main` 分支 |

### Runner 标签

流水线 Job 使用以下标签匹配 Runner：

```
gitlab-duo, docker
```

> Runner 已在 `docker-compose.yml` 中预配置这些标签，无需手动注册。

---

## ⚙️ 配置说明

### 环境变量（`.env`）

```env
# GitLab CE 版本
GITLAB_VERSION=17.11.1-ce.0

# GitLab Runner 版本
RUNNER_VERSION=v17.11.1

# Runner 注册 Token（由 deploy 脚本自动获取）
RUNNER_TOKEN=
```

### 端口映射

| 宿主机端口 | 容器端口 | 用途 |
|-----------|---------|------|
| `80` | `80` | HTTP |
| `443` | `443` | HTTPS |
| `2222` | `22` | SSH（避免与本地 SSH 冲突） |

> 端口 22 已修改为 **2222**，避免与宿主机 SSH 服务冲突（[BUG-GITLAB-003](bugs/BUG-GITLAB-003.md)）。

---

## 🔐 首次访问

| 项目 | 值 |
|------|-----|
| URL | `http://localhost` |
| 账号 | `root` |
| 密码 | 由 `deploy.sh` 自动输出，或执行 `docker exec gitlab cat /etc/gitlab/initial_root_password` |

---

## 🐛 已知问题

完整的 Bug 报告见 [`bugs/`](bugs/) 目录。

| 标号 | 标题 | 严重度 | 状态 |
|------|------|--------|------|
| BUG-GITLAB-001 | CI/CD 流水线全部为 Mock 实现 | Critical | ✅ 已修复 |
| BUG-GITLAB-002 | `external_url` 配置错误 | High | ✅ 已修复 |
| BUG-GITLAB-003 | 端口 22 与本地 SSH 冲突 | High | ✅ 已修复 |
| BUG-GITLAB-005/006 | Token 获取命令错误（Windows 命令用于 Linux 容器） | Critical | ✅ 已修复 |
| BUG-GITLAB-008 | 源码目录为空 | High | ✅ 已修复 |
| BUG-GITLAB-012 | 健康检查依赖 `curl` 单点故障 | High | ✅ 已修复 |
| BUG-GITLAB-013 | 废弃的 `version` 属性 | Low | ✅ 已修复 |
| BUG-GITLAB-014 | 缺少 `.env` 时 `RUNNER_TOKEN` 警告 | Medium | ⏳ 待修复 |
| BUG-GITLAB-015 | 镜像体积过大（2.5GB+），首次部署慢 | Medium | ⏳ 待修复 |
| 其余 | 超时保护、Job 命名等 | Med/Low | ✅ 已修复 |

---

## 🧹 清理

```bash
# 停止并删除所有容器
docker compose -f gitlab/docker-compose.yml down -v

# 删除持久化数据
rm -rf gitlab/runtime/

# 删除镜像
docker rmi gitlab/gitlab-ce:17.11.1-ce.0
docker rmi gitlab/gitlab-runner:v17.11.1
```

---

## 📄 License

MIT