# alpinePHP环境

**Repository Path**: json_decode/alpine-php-environment

## Basic Information

- **Project Name**: alpinePHP环境
- **Description**: aloine PHP 环境
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-07-29
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 本地 PHP 开发栈 + 简易面板

中间件用官方镜像；PHP = 官方 `php:<patch>-fpm-alpine` + 统一薄 Dockerfile。  
编排入口：`start.sh` / `start.ps1`；管理面板：宿主机 Go 二进制（`127.0.0.1:10240`）。

需求与架构决策见 `REQUIREMENTS.md`（产品规格，不是使用手册）。

---

## 目录：保留 / 忽略 / 已删除

### 应保留（仓库核心）

| 路径 | 说明 |
|------|------|
| `start.sh` / `start.ps1` | 唯一 CLI 入口 |
| `docker-compose.yml` | 中间件（nginx/redis/mysql/postgres） |
| `dockerfiles/php/Dockerfile` | **唯一** PHP 构建模板 |
| `versions.yml` | 运行钉点（当前启用的 PHP / 中间件镜像） |
| `versions.catalog.yml` | 商店可用版本（可刷新） |
| `script/fetch-versions.py` | 拉 Docker Hub → catalog |
| `script/render-stack.py` | 生成 PHP compose + 同步 `.env` 数据目录 |
| `panel/` | Go 面板源码 |
| `data/nginx/` | nginx 配置、站点 conf、`sites.json` |
| `data/php*/conf/` | 各槽位 `php.ini` |
| `data/redis/conf/` | redis 配置 |
| `.env.example` | 环境变量模板 |
| `REQUIREMENTS.md` | 需求 / Spec 决策 |

### 生成物 / 本地运行时（不入库或已 gitignore）

| 路径 | 说明 |
|------|------|
| `.env` | 本地密码、镜像覆盖、数据目录（从 example 复制） |
| `bin/panel`（`.exe`） | 面板编译产物 |
| `docker-compose.php.yml` | 由 render 生成 |
| `docker-compose.bypass.yml` | 辅路启用时生成 |
| `data/mysql/<系列>/`、`data/postgres/`、`data/redis/<系列>/` | 数据库数据 |
| `data/*/logs/` | 日志 |
| `data/bypass.json` | 辅路登记（大版本切换后产生） |
| `script/__pycache__/` | Python 缓存 |

### 已删除 / 不要再加回来

| 路径 | 原因 |
|------|------|
| `dockerfiles/php74/`、`dockerfiles/php82/` | 旧分槽 Dockerfile，已统一到 `dockerfiles/php/` |
| 根目录 / `data` 下 `.DS_Store` | 系统垃圾 |
| `script/__pycache__/` | 构建缓存 |

业务代码不在本仓库：默认挂载宿主机 `PROJECT_DIR` → 容器 `/www`。

---

## 环境要求

- Docker + Docker Compose v2
- Python 3（render / 刷新 catalog）
- 编译面板时需要 Go 1.21+（若已有 `bin/panel` 可跳过）

---

## 安装与打包

### 1. 克隆后初始化

```bash
cp .env.example .env
# macOS/Linux：PROJECT_DIR 默认 /www
# Windows：建议改成 WSL 内路径（如 /home/you/www），避免 D:\ 绑定挂载过慢
mkdir -p "${PROJECT_DIR:-/www}"   # 或按 .env 里的路径创建
```

### 2. 启动开发栈

```bash
./start.sh up -d          # macOS / Linux / WSL
# 或
.\start.ps1 up -d         # Windows PowerShell
```

`start.sh` / `start.ps1` 会先执行 `render-stack.py`，再：

```text
docker compose -f docker-compose.yml -f docker-compose.php.yml
# 若存在辅路：再加 -f docker-compose.bypass.yml
```

### 3. 编译 / 打包面板

**本机编译（推荐日常）：**

```bash
./start.sh panel-build    # → bin/panel
.\start.ps1 panel-build   # → bin/panel.exe
```

**交叉编译示例（可选分发）：**

```bash
cd panel
# macOS Apple Silicon
GOOS=darwin  GOARCH=arm64 go build -o ../bin/panel .
# macOS Intel
GOOS=darwin  GOARCH=amd64 go build -o ../bin/panel .
# Linux
GOOS=linux   GOARCH=amd64 go build -o ../bin/panel .
# Windows
GOOS=windows GOARCH=amd64 go build -o ../bin/panel.exe .
```

分发时建议带上：整个仓库（或至少 compose / versions / dockerfiles / script / data 配置）+ 对应平台的 `bin/panel`；**不要**把 `.env`、数据库目录打进包。

面板**不是** Docker 镜像：跑在宿主机，调用本机 `docker compose`。

### 4. 启动面板

```bash
./start.sh panel
# 浏览器打开 http://127.0.0.1:10240
```

若无 `bin/panel` 且本机有 Go，会回退为 `go run`。

---

## 使用方式

### 常用命令

```bash
./start.sh up -d
./start.sh down
./start.sh ps
./start.sh logs -f nginx
./start.sh build php82          # 重建某个 PHP 槽位镜像
./start.sh pull nginx redis mysql
./start.sh panel-build && ./start.sh panel
```

也可：

```bash
python3 script/fetch-versions.py   # 刷新 versions.catalog.yml（面板商店页也可点）
python3 script/render-stack.py     # 仅重新生成 compose / 同步 .env
```

### 端口（默认）

| 服务 | 宿主机端口 | 说明 |
|------|------------|------|
| nginx | 80 / 443 | 站点入口 |
| mysql | 3306 | 主路 |
| postgres | 5432 | 主路 |
| redis | 6379 | 主路 |
| PHP-FPM | — | 默认仅容器网络，不映射宿主机 |
| panel | 10240 | 仅本机访问 |

辅路（旧系列临时启用）端口自选，默认建议 `3307` / `5433` / `6380`。

### 面板能做什么

- **容器**：查看状态 / 端口  
- **软件**：已装 PHP、中间件；**辅路**启停、删除（可选删数据目录）  
- **软件商店**：安装/切换 PHP 与中间件版本（带进度）  
- **网站**：表单管理站点 conf；可勾选 **HTTPS**（自签证书，可选 80→443）  
- **大版本切换**：新版本占主路标准端口 + 新数据目录；旧目录登记为辅路（默认不启）

HTTPS 证书目录：`data/nginx/ssl/<站点 id>/`。生成策略：**本机有 mkcert 则用 mkcert**，否则自签。

消除浏览器警告：

```bash
# macOS
brew install mkcert nss && mkcert -install

# Windows (scoop / choco)
scoop install mkcert
mkcert -install

# Linux 见 https://github.com/FiloSottile/mkcert
```

然后在面板对该站点勾选「重新生成证书」并保存。

启用 HTTPS 后若 nginx 尚未挂载 `ssl` 目录，执行一次：

```bash
./start.sh up -d nginx
```

### 改版本改哪里

| 要改 | 文件 / 入口 |
|------|-------------|
| PHP 系列 / patch / 扩展 / 启停 | `versions.yml` 或面板 |
| nginx / redis / mysql / postgres 镜像 | `versions.yml`（会同步到 `.env`） |
| php.ini | `data/<slot>/conf/php.ini` 或面板「配置」 |
| 站点 | 面板「网站」，或 `data/nginx/sites.json` + 生成的 `site-*.conf` |
| 密码、`PROJECT_DIR` | `.env` |

小版本升级：改钉点 → `build` / `pull` → **重建容器**。禁止在容器内原地升级。

### 数据目录约定

```text
data/mysql/8.4/     data/mysql/9.4/     …   # 按系列，主路只挂当前系列
data/postgres/17/
data/redis/7.2/
data/php74/  data/php82/                     # 槽位配置与日志
data/bypass.json                             # 辅路登记
```

---

## 结构一览

```text
.
├── start.sh / start.ps1
├── docker-compose.yml
├── docker-compose.php.yml      # 生成，勿手改
├── docker-compose.bypass.yml   # 辅路启用时生成
├── versions.yml
├── versions.catalog.yml
├── .env.example → .env
├── dockerfiles/php/Dockerfile
├── script/
│   ├── fetch-versions.py
│   └── render-stack.py
├── panel/                      # Go 源码 → bin/panel
├── data/
├── REQUIREMENTS.md             # 需求 / 决策
└── README.md                   # 本说明
```

```text
versions.yml ──render-stack──► docker-compose.php.yml + .env 数据目录
      ▲
Go 面板 :10240 ── docker compose ──► 容器（网络 dev）
```