README

基于Roadiz v2+构建的无头API项目骨架

安装

COMPOSER_MEMORY_LIMIT=-1 composer create-project roadiz/skeleton my-website

通过复制 .env 到 .env.local 来自定义配置

cp .env .env.local

确保在更改用于容器初始化的变量（MySQL / Solr / SMTP凭据）时，告诉docker-compose使用 .env.local。Roadiz应用将读取 .env，然后使用您的 .env.local 覆盖变量。这就是为什么.env 文件已提交到Git存储库，并且它不得包含任何秘密。

如果Composer对内存限制问题提出异议，只需在前面加上 COMPOSER_MEMORY_LIMIT=-1。

根据您的本地环境编辑您的 .env.local 和 docker-compose.yml 文件。

docker compose build
docker compose up -d --force-recreate

然后等待您的服务初始化，特别是您的 数据库 初始化可能需要几秒钟（文件系统、数据库和用户创建）。

当您准备好时，您可以通过Docker服务检查 Symfony 控制台是否响应

docker compose exec -u www-data app bin/console

使用 symfony server:start 代替Docker

如果您在 macOS 环境中工作，您可能更愿意使用 symfony 二进制文件来启动本地Web服务器，而不是使用完整的 Docker 堆栈。您首先需要安装 symfony 二进制文件。

curl -sS https://get.symfony.com/cli/installer | bash

并且确保您的本地PHP环境配置了php-intl、php-redis、php-gd扩展。您需要使用Docker堆栈中的至少 MySQL 和 Redis（如果需要，还有 Solr）服务才能运行您的应用程序。

docker compose -f docker-compose.symfony.yml up -d 

• 将您的 .env.local 变量配置为使用您的本地MySQL和Redis服务。将 db、redis、mailer 和 solr 主机名替换为 127.0.0.1。请确保在 macOS 上使用 127.0.0.1 而不是 localhost，因为它与Docker不兼容。
• 从 Makefile 中的所有命令中移除 docker compose exec -u www-data app 前缀以在本地执行配方。
• 从 config/packages/api_platform.yaml 和 config/packages/roadiz_core.yaml 文件中移除缓存无效化Varnish配置。

然后您可以启动您的本地Web服务器

symfony serve -d

执行上述所有安装步骤，不使用 docker compose exec 命令。

然后您的Roadiz后台办公室将在 https://127.0.0.1:8000/rz-admin 可用

生成 Symfony秘密

当您第一次运行 composer create-project 时，以下命令应已自动执行

docker compose exec -u www-data app bin/console secrets:generate-keys

然后为您配置变量生成秘密值，如 APP_SECRET 或 JWT_PASSPHRASE

docker compose exec -u www-data app bin/console secrets:set JWT_PASSPHRASE --random
docker compose exec -u www-data app bin/console secrets:set APP_SECRET --random

请确保您从 .env 和 .env.local 文件中删除这些变量，这将覆盖您的秘密（例如空值），并且会失去加密秘密的所有好处。

生成JWT私钥和公钥

使用内置命令生成您的密钥对（以下命令应在 composer create-project 时自动执行）

docker compose exec -u www-data app bin/console lexik:jwt:generate-keypair

或手动使用 openssl

# Reveal your JWT_PASSPHRASE
docker compose exec -u www-data app bin/console secrets:list --reveal
# Fill JWT_PASSPHRASE env var.
openssl genpkey -out config/jwt/private.pem -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096;
openssl pkey -in config/jwt/private.pem -out config/jwt/public.pem -pubout;

安装数据库

使用 make install 命令安装您的数据库模式和示例数据。

或手动

# Create Roadiz database schema
docker compose exec -u www-data app bin/console doctrine:migrations:migrate
# Migrate any existing data types
docker compose exec -u www-data app bin/console app:install
# Install base Roadiz fixtures, roles and settings
docker compose exec -u www-data app bin/console install
# Clear cache
docker compose exec -u www-data app bin/console cache:clear
# Create your admin account
docker compose exec -u www-data app bin/console users:create -m username@roadiz.io -b -s username

管理节点类型

可以通过后台办公室界面或通过编辑 src/Resources/node-types 目录中的JSON文件来管理节点类型。如果您手动编辑JSON文件，则需要同步您的数据库与这些文件，并在导致数据库模式更改的情况下生成Doctrine迁移。

迁移节点类型

当您直接更新 node-types JSON文件时，您需要将它们添加到 src/Resources/config.yml 中，并运行以下命令以更新数据库

make migrate

此命令将 更新PHP实体，并在必要时创建一个Doctrine迁移文件。

应用节点类型迁移

当你拉取项目，只想同步你的本地节点类型时，你需要应用迁移

make update

这将 仅加载尚未在数据库中存在的节点类型。但不会创建任何迁移。这与你在运行 make install 时执行的脚本相同，以及在你的Docker镜像entrypoint中。

功能

• 配置为与 API Platform 无头模式一起使用
• 与 lexik/jwt-authentication-bundle 配置
• 所有Docker开发和生产环境
• 用于执行symfony/messenger消费者的Supervisor守护进程
• 直接提供Solr和Varnish服务
• Gitlab CI就绪
• 使用 phpcs 和 phpstan 确保代码质量和静态分析
• 包含2个 节点类型： Menu 和 MenuLink，以便在你的 /api/common_content 响应中创建自动菜单

通用内容端点

/api/common_content 端点是用来公开关于你网站的一些常用数据。你可以在网站前端一次性获取这个端点，而不是在每个Web响应中嵌入相同的数据。menus 条目将自动包含任何根级别的 Menu 树遍历。

{
    "@context": "/api/contexts/CommonContent",
    "@id": "/api/common_content?id=unique",
    "@type": "CommonContent",
    "home": {
        "@id": "/api/pages/1",
        "@type": "Page",
        "title": "home",
        "publishedAt": "2021-09-09T02:23:00+02:00",
        "node": {
            "@id": "/api/nodes/1",
            "@type": "Node",
            "nodeName": "home",
            "visible": true,
            "tags": []
        },
        "translation": {
            "@id": "/api/translations/1",
            "@type": "Translation",
            "name": "English",
            "defaultTranslation": true,
            "available": true,
            "locale": "en"
        },
        "slug": "home",
        "url": "/"
    },
    "head": {
        "@type": "NodesSourcesHead",
        "googleAnalytics": null,
        "googleTagManager": null,
        "matomoUrl": null,
        "matomoSiteId": null,
        "siteName": "Roadiz dev website",
        "metaTitle": "Roadiz dev website",
        "metaDescription": "Roadiz dev website",
        "policyUrl": null,
        "mainColor": null,
        "facebookUrl": null,
        "instagramUrl": null,
        "twitterUrl": null,
        "youtubeUrl": null,
        "linkedinUrl": null,
        "homePageUrl": "/",
        "shareImage": null
    },
    "menus": {
        "mainMenuWalker": {
            "@type": "MenuNodeSourceWalker",
            "children": [],
            "item": { ... },
            "childrenCount": 0,
            "level": 0,
            "maxLevel": 3
        }
    }
}

版本控制

确保你的 .env 文件不包含任何敏感数据，因为它必须添加到你的仓库中：git add --force .env 以便被 .env.local 文件覆盖。敏感和本地数据必须在 .env.local 中填写，它是git忽略的。

在生产环境中使节点类型可编辑

你可能想在部署Roadiz v2应用并编辑你的节点类型模式后（无需任何Git版本控制）。你可以在这3个目录上设置并启用Docker卷，以便在Docker重启之间持久化你的配置。

• config/api_resources
• src/Resources
• src/GeneratedEntity

请注意，如果你想在本地环境中复制你的设置，你必须下载你的节点类型JSON文件。

我们不推荐在需要控制并版本控制节点类型模式的复杂应用程序中使用此工作流程。这仅适用于小型和基本网站。

常规提交

本项目使用常规提交来自动化发布流程和 changelog 生成，使用 git-cliff。在此骨架中已提供 cliff.toml 配置文件。

生成CHANGELOG文件

git-cliff -o CHANGELOG.md

在发布前

• 在有已知标签的情况下

  git-cliff -o CHANGELOG.md --tag 1.0.0

• 在没有知道标签的情况下，让 git-cliff 寻找正确的版本

  git-cliff -o CHANGELOG.md --bump

致谢

此骨架使用 https://github.com/vishnubob/wait-for-it 脚本来等待MySQL就绪，然后再启动应用entrypoint。