seanmorris/ids.aptcache

SeanMorris/Ids v00.0.0

PHP + Docker框架，提供Web应用开发的核心功能抽象与多环境部署支持。

镜像概述和主要用途

SeanMorris/Ids（简称Ids）是一个集成PHP和Docker的Web开发框架，旨在为Web应用提供通用领域原语。它将路由、请求处理、配置管理、日志记录、会话管理和数据库访问等核心功能抽象为简洁且高效的接口，帮助开发者构建安全、快速且易于维护的应用。Ids支持在Docker环境中运行，也可作为Composer包集成到现有项目，适用于从开发、测试到生产的全流程部署。

核心功能和特性

核心功能

• 领域原语抽象：封装路由、请求、配置、日志、会话和数据库访问等基础功能，提供统一接口。
• 严格错误处理：默认对所有错误（包括E_NOTICE级别）终止执行，排除 vendor 目录产生的E_DEPRECATED错误，确保代码稳定性。
• 多环境支持：提供base、prod、dev、test四种构建目标，各目标暴露不同端口，可并行运行无冲突。
• Idilic CLI工具：全局安装后提供idilic命令，支持项目检测、环境控制和功能扩展。
• Docker多阶段构建：支持通过make命令构建不同环境镜像，集成Docker Compose实现服务编排。
• 服务扩展：通过+工具名语法（如@dev+graylog）临时启用额外服务（如Graylog、Inotify）。

关键特性

• 安全优先：设计理念以安全性、速度和易用性为核心，优先保障应用安全。
• 配置灵活：支持环境变量、.env文件、YAML/JSON配置，支持主机和端口级别的配置覆盖。
• 自动标签与发布：集成Git钩子，基于Git标签、提交哈希和日期自动生成镜像标签，支持分支级别的自动构建与推送。
• 开发工具集成：内置XDebug调试支持、Apt缓存加速构建、Graylog日志管理等开发辅助工具。

使用场景和适用范围

Ids适用于各类PHP Web应用开发，尤其适合需要：

• 快速搭建多环境（开发、测试、生产）部署流程的项目。
• 依赖统一接口管理路由、数据库等核心功能的团队。
• 注重安全性和性能优化的Web应用。
• 需集成Docker容器化部署的PHP项目。

使用方法和配置说明

安装

项目内集成

通过Composer将Ids添加到现有项目：

bash
composer require seanmorris/ids

全局安装Idilic CLI

全局安装以使用idilic命令行工具：

bash
composer global require seanmorris/ids:dev-master

将Composer全局vendor/bin添加到环境变量（如~/.bashrc）：

bash
export PATH="$HOME/.composer/vendor/bin:$PATH"

创建新项目

使用Composer创建Ids项目模板，并启动服务：

bash
composer create-project seanmorris/ids-project -s dev --remove-vcs
cd ids-project
make @dev start-bg  # 启动php、apache、mysql服务（后台运行）

项目模板地址：https://github.com/seanmorris/ids-project

依赖要求

• Composer
• Docker & Docker Compose
• GNU Make
• Git
• Linux或兼容OS
• PHP（支持7.1+版本）
• SimpleTest（测试依赖）
• Minikube（仅Kubernetes目标需要）

构建与环境目标

环境目标说明

Ids默认提供4种构建目标，特性如下：

• base：无端口暴露，不含require-dev依赖。
• prod：暴露80（HTTP）和443（HTTPS，待实现）端口，不含require-dev依赖。
• dev：暴露2020（HTTP）和3030（SQL）端口，含require-dev依赖，适合开发。
• test：暴露2021（HTTP）和3031（SQL）端口，含require-dev依赖，用于测试。

切换环境目标

通过make @目标名 命令临时指定目标，或make stay@目标名持久切换：

bash
make @dev build       # 临时使用dev目标构建
make stay@test        # 持久切换到test目标

扩展环境目标

1. 在项目中创建infra/compose/[TARGET].yml定义Docker Compose配置。
2. 在config/目录下创建.env.[TARGET]设置目标特定环境变量。
3. 在infra/docker中添加Dockerfile的FROM base as TARGET部分定义构建步骤。

服务控制

启动/停止/重启

bash
make start         # 后台启动服务（无输出）
make start-fg      # 前台启动服务（实时输出）
make start-bg      # 后台启动服务（前台流式输出日志）
make stop          # 停止当前目标的所有服务
make stop-all      # 停止当前目标的所有相关服务（包括已移除配置的服务）
make restart       # 后台重启服务（无输出）
make restart-fg    # 前台重启服务（实时输出）
make restart-bg    # 后台重启服务（前台流式输出日志）

镜像管理

bash
make list-images   # 列出当前项目、目标和分支的所有镜像
make list-tags     # 列出当前项目、目标和分支的所有镜像标签
make push-images   # 推送当前项目、目标和分支的所有镜像
make pull-images   # 拉取当前项目、目标和分支的所有镜像

自动标签与发布

1. 执行make hooks注册Git钩子。
2. 镜像标签自动基于Git标签（或提交哈希）和日期生成：
   • master分支：仓库/项目:gitTag-target、仓库/项目:date-target、仓库/项目:latest-target。
   • 其他分支：仓库/项目:gitTag-target-branch、仓库/项目:date-target-branch、仓库/项目:latest-target-branch。
3. 在项目根目录.publishing文件中定义发布规则（如master:prod），实现git push时自动推送镜像。

可用镜像

Docker Hub提供以下镜像，支持base、dev、test目标：

• idilic：https://hub.docker.com/repository/docker/seanmorris/ids.idilic
• server：https://hub.docker.com/repository/docker/seanmorris/ids.server

拉取镜像：

bash
docker pull seanmorris/ids.idilic:latest
docker pull seanmorris/ids.server:latest

扩展镜像（不建议使用latest标签）：

Dockerfile
FROM seanmorris/ids.idilic:TAGNAME
FROM seanmorris/ids.server:TAGNAME

配置管理

环境变量与配置文件

配置可通过环境变量或.env文件设置，优先级从高到低为： .env_TARGET > .env_TARGET.default > .env > .env.default

• 非敏感配置：在config/.env.default或config/.env.[TARGET].default中定义（可提交至版本控制）。
• 敏感配置：在config/.env或config/.env.[TARGET]中定义（不提交至版本控制）。

配置读取

环境变量以IDS_为前缀，支持多级结构，例如：

bash
IDS_SOME_VAR=value
IDS_SOME_OTHERVAR=other value

在PHP中通过Settings类读取：

php
use \SeanMorris\Ids\Settings;

$someVar = Settings::read('some', 'var');          // 读取IDS_SOME_VAR
$someOtherVar = Settings::read('some', 'otherVar');// 读取IDS_SOME_OTHERVAR
$some = Settings::read('some');                    // 获取包含var和otherVar的对象

数组配置

通过变量名加下划线_定义数组，值以空格分隔（引号内保留空格）：

bash
IDS_ARRAY_=first "second element" "third ""with quotes""."

读取：

php
$array = Settings::read('ARRAY'); // 结果：['first', 'second element', 'third "with quotes".']

主机和端口特定配置

通过IDS__主机名__端口__变量名格式覆盖特定主机/端口的配置（主机名中非字母数字替换为_，连字符替换为___）：

bash
IDS__EXAMPLE_COM__80__SOME_VAR=HTTP值       # example.com:80的SOME_VAR
IDS__EXAMPLE_COM__443__SOME_VAR=HTTPS值     # example.com:443的SOME_VAR

读取方式不变，系统自动根据当前请求的主机和端口匹配配置。

密钥管理

• 临时随机密钥：在.entropy文件中定义CONFIG_KEY:ENTROPY_KEY（如DB_PASSWORD:db），启动时自动生成32位随机值并写入.env。
• 生产环境密钥：建议通过环境变量注入，避免存储在文件中。

YAML/JSON配置

在config/[主机名]/或config/[主机名;端口]/目录下放置settings.yml或settings.json，支持主机/端口级别的配置。默认配置可放在settings.defaults.yml或settings.defaults.json（可提交至版本控制）。

开发工具

XDebug

dev镜像内置XDebug，通过.env.dev中的XDEBUG_CONFIG_环境变量配置，默认连接DHOST_IP的9000端口。

Graylog日志

通过设置环境变量启用Graylog日志：

bash
IDS_LOGGERS_=\SeanMorris\Ids\Logger\Gelf
IDS_GRAYLOG_HOST=graylog
IDS_GRAYLOG_PORT=12201

启动Graylog服务：

bash
make @dev+graylog start  # 启动dev环境并启用Graylog
make graylog-restore     # 恢复默认GELF TCP输入配置

模板文件

扩展名为*.idstmp.*的文件会被预处理为*.___gen.*，支持Makefile语法（如变量替换、Shell命令），例如：

dockerfile
# infra/docker/aptcache.idstmp.dockerfile
FROM ${BASELINUX}
# generated @ $(shell date)