# ul-php-docker-env

**Repository Path**: ulthon/ul-php-docker-env

## Basic Information

- **Project Name**: ul-php-docker-env
- **Description**: 使用docker部署通用php环境的资料。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2024-10-14
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ul-php-docker-env

**轻量级服务器运维方案** - 基于配置文件 + Docker 的服务器管理框架

## 核心定位

**不使用面板，也能优雅管理服务器**

- ✅ 配置即代码 - 所有配置文件化，Git 版本控制
- ✅ Docker 容器化 - 服务隔离，易于迁移
- ✅ **虚拟机式管理** - 每个项目像一个独立的虚拟机
- ✅ **统一基础服务** - HTTP、定时任务、进程守护、备份、数据库等
- ✅ **多服务多域名** - 一个项目可以包含多个服务、多个域名、多个端口
- ✅ 快速迁移 - 有状态项目也能达到无状态效果
- ✅ **AI 友好** - 结构化配置，易于智能体理解和操作

---

## 技术选型

| 组件 | 技术 | 说明 |
|------|------|------|
| 容器运行时 | Docker | 所有服务容器化 |
| 反向代理 | Caddy | 自动 HTTPS，配置简洁 |
| 管理脚本 | ThinkPHP 8 | 命令行 + Web 界面 |
| 运行时 | FrankenPHP | 打包为原生二进制 |

### 管理脚本方案

**最终决策：原生二进制 + FrankenPHP**

**为什么不用 Docker 容器化：**
- ❌ 权限复杂 - Docker Socket 权限过高
- ❌ 功能受限 - AI 对接、系统调用不便
- ❌ 部署复杂 - 需要先有 Docker 才能用

**为什么用 FrankenPHP：**
- ✅ 单一二进制 - 无需安装 PHP
- ✅ 原生权限 - 直接访问系统
- ✅ AI 友好 - 可内置 AI 功能
- ✅ 性能更好 - 无容器开销

---

## 设计理念

### 1. 配置文件优先

不依赖黑盒面板，直接管理配置文件：

```
projects/{project-name}/
├── docker/       # Docker 服务配置
├── caddy/        # Caddy 站点配置
├── cron/         # 定时任务配置（待实现）
├── site/         # 源码（PHP/前端）
└── backup/       # 备份目录
```

主程序（Caddy、Cron）会自动加载项目级配置。

### 2. 项目级隔离

每个项目独立目录，互不影响：

```
/data/projects/
├── my-blog/
│   ├── docker/compose.yaml
│   ├── caddy/Caddyfile
│   └── site/
├── my-api/
│   ├── docker/compose.yaml
│   ├── caddy/Caddyfile
│   └── site/
└── ...
```

### 3. 端口规范

| 服务类型 | 端口规则 | 示例 |
|----------|----------|------|
| PHP-FPM | 9{version}0 | 9740, 9800, 9810, 9820 |
| MySQL | 3{version}0 | 3570, 3800 |
| Redis | 6379 | 6379 |
| 自定义应用 | 10000+ | 10001, 10002... |

### 4. 最小端口暴露

只需映射三个端口即可：
- **HTTP** - 80
- **HTTPS** - 443
- **SSH** - 22

---

## 设计理念

### 虚拟机式项目管理

每个 `projects/{project-name}/` 目录就像一台独立的虚拟机：

```
projects/my-project/
├── docker/           # 多个 Docker 服务
│   ├── compose.yaml  # 可以定义多个容器
│   ├── api.yaml      # API 服务
│   └── worker.yaml   # 后台任务
├── caddy/
│   └── Caddyfile     # 多域名、多端口配置
├── cron/             # 定时任务
├── supervisor/       # 进程守护（可选）
└── backup/           # 备份数据
```

**核心特性：**

| 特性 | 说明 |
|------|------|
| **多服务** | 一个项目可以运行多个 Docker 容器 |
| **多域名** | 一个项目可以配置多个域名 |
| **多端口** | 一个项目可以暴露多个端口 |
| **统一服务** | 使用统一的基础服务（Caddy、Cron、Supervisor） |
| **灵活配置** | Caddyfile 可随意配置，内置指令简化操作 |

### 统一基础服务

**所有项目共享：**

```
server/
├── caddy/          # 统一 HTTP 服务
│   ├── Caddyfile   # 全局配置
│   └── lib/        # 内置配置片段
├── php*/           # PHP 运行环境
├── mysql*/         # 数据库服务
├── redis/          # 缓存服务
└── docker/         # Docker 镜像配置
```

**项目级配置：**

```caddyfile
# projects/my-project/caddy/Caddyfile

# 域名 1 - 主站
my-project.com {
    import php81 my-project
}

# 域名 2 - API
api.my-project.com {
    import proxy localhost:3000
}

# 端口服务
:38080 {
    respond "Internal API"
}
```

### 内置配置片段

`server/caddy/lib/` 提供常用配置：

| 片段 | 用途 |
|------|------|
| `common_site` | 通用站点配置 |
| `php81` | PHP 8.1 FastCGI |
| `tp8` | ThinkPHP 8 配置 |
| `proxy` | 反向代理 |
| `cors_all` | CORS 配置 |

**使用方式：**

```caddyfile
my-project.com {
    import php81 my-project  # 使用 PHP 8.1
    import cors_all          # 启用 CORS
}
```

---

## 目录结构

```
/data/
├── projects/                    # 所有项目
│   ├── {project-name}/
│   │   ├── docker/             # Docker 服务
│   │   ├── caddy/              # Caddy 配置
│   │   ├── cron/               # 定时任务（待实现）
│   │   ├── site/               # 源码
│   │   └── backup/             # 备份
│   ├── ul-proxy/               # 内置：SSH 代理
│   ├── ul-nexus/               # 内置：Nexus 镜像
│   ├── ul-ddns/                # 内置：DDNS
│   └── ...
│
├── server/                      # 基础服务
│   ├── caddy/                  # 反向代理
│   ├── docker/                 # Docker 安装
│   ├── lib/                    # 管理脚本
│   ├── ln/                     # 软连接管理
│   ├── php{74,80,81,82}/       # PHP 多版本
│   ├── mysql{57,80}/           # MySQL 多版本
│   └── redis/                  # Redis
│
└── backup/                      # 备份存储
```

---

## 内置服务

以 `ul-` 开头的是内置项目模板：

| 服务 | 目录 | 说明 |
|------|------|------|
| SSH 代理 | `ul-proxy/` | 通过 SSH 隧道提供代理 |
| Nexus | `ul-nexus/` | Docker/NPM 镜像服务 |
| DDNS | `ul-ddns/` | 动态 DNS |
| 文件管理 | `ul-filebrowser/` | Web 文件管理器 |
| CI Runner | `ul-gitea-runner/` | Gitea Actions Runner |

---

## 快速开始

> 💡 **首次部署？** 请阅读 [快速开始指南](./doc/QUICKSTART.md)

### 1. 安装 Docker

```bash
bash /data/server/docker/install.sh
```

### 2. 启动基础服务

```bash
cd /data/server/caddy && docker compose up -d
```

### 3. 创建项目

```bash
# 复制模板
cp -r /data/projects/default /data/projects/my-project

# 修改配置
vim /data/projects/my-project/docker/compose.yaml
vim /data/projects/my-project/caddy/Caddyfile

# 启动项目
cd /data/projects/my-project/docker && docker compose up -d

# 重载 Caddy
docker exec ul-caddy caddy reload --config /etc/caddy/Caddyfile
```

---

## 管理脚本（计划中）

使用 ThinkPHP + FrankenPHP 实现统一管理：

```bash
# 创建项目
./ul-php-docker-env project:create my-project

# 管理数据库
./ul-php-docker-env database:create mydb --version=80

# 备份恢复
./ul-php-docker-env backup:project my-project
./ul-php-docker-env restore:project my-project

# 服务管理
./ul-php-docker-env service:up php81
./ul-php-docker-env service:down mysql80
```

Web 界面（计划中）：访问 `http://localhost:8080` 进行可视化管理。

---

## PHP 部署经验

### 容器化 PHP 的优势

- ✅ 多版本共存（7.4, 8.0, 8.1, 8.2）
- ✅ 环境隔离
- ✅ 易于迁移

### 已知局限性

| 场景 | 问题 | 状态 |
|------|------|------|
| PHP-FPM | ✅ 正常工作 | 可用 |
| 命令行调用 | ⚠️ 可用，但有局限 | 基本可用 |
| 守护进程 | ❌ 无法正常终止 | 不推荐 |
| 定时任务 | ⚠️ 需要特殊处理 | 待实现 |

**命令行局限性说明：**

宿主机调用容器内的长期运行进程无法正常终止：
- 原因：无法创建 TTY，无法正确杀死进程
- 建议：优先使用 Docker 容器自己的守护进程机制

**结论：** 优先以运行 Docker 为主，让项目自己解决服务、守护进程问题。

---

## 文档

- [安装文档](./server/0_INSTALL.md)
- [项目规划](./doc/ROADMAP.md)
- [PHP 命令行说明](./doc/PHP_COMMAND.md)

---

## 命名规范

### projects 目录

| 类型 | 命名规则 | 示例 |
|------|----------|------|
| 内置服务 | `ul-{name}` | `ul-proxy`, `ul-nexus` |
| 业务项目 | 自定义 | `my-blog`, `api-server` |
| 测试项目 | `hello-world`, `test-*` | `hello-world` |

### server 目录

| 目录 | 用途 |
|------|------|
| `ul-*` | 内置服务模板 |
| `php{version}` | PHP 运行环境 |
| `mysql{version}` | 数据库 |
| `lib` | 管理脚本 |
| `ln` | 软连接管理 |

---

## AI 智能体优化

本项目的管理规范非常适合 AI 使用，设计时充分考虑了智能体友好性：

### 为什么适合 AI

| 特性 | 说明 |
|------|------|
| **配置文件化** | 所有配置都是可读的文本文件，AI 可直接理解和修改 |
| **目录结构规范** | 统一的目录结构，AI 容易学习和操作 |
| **命名规范** | `ul-*` 前缀、`docker/`、`caddy/` 等语义化命名 |
| **项目级隔离** | 每个项目独立，AI 可逐个项目理解和操作 |

### AI 技能生成（计划）

本项目将提供 OpenClaw 技能文件（`SKILL.md`），让 AI 智能体能够：

1. **创建项目** - 根据模板快速创建新项目
2. **管理服务** - 启停、监控服务状态
3. **配置域名** - 自动生成 Caddy 配置
4. **备份数据** - 按规范执行备份操作
5. **故障排查** - 根据日志和配置定位问题

### AI 规则示例

```
# 创建项目规则
1. 检查项目名称是否符合规范
2. 从 default/ 复制模板
3. 修改 docker/compose.yaml
4. 修改 caddy/Caddyfile
5. 启动服务并验证

# 服务管理规则
1. 检查服务状态: docker compose ps
2. 查看日志: docker compose logs
3. 重启服务: docker compose restart
4. 验证服务: curl health check
```

### 优化方向

- [ ] 生成 `SKILL.md` 文件
- [ ] 生成 OpenClaw 技能包
- [ ] 提供常见操作的 AI 提示词模板
- [ ] 记录 AI 操作日志，便于审计

---

## 许可证

木兰宽松许可证，第2版（MulanPSL v2）

---

## 维护者

- augushong
- 惠虾米（AI 助手）