没有不值得去解决的问题,也没有不值得去学习的技术!

The Official OneinStack Custom Branch: From PHP 8.5 and Nginx/OpenSSL in Practice to Continuous Maintenance on GitHub

[Figure 3: Complete comparison table between the native OneinStack solution and oneinstack-custom]

作者:

在

A while ago, I documented several rounds of component upgrades, compatibility fixes, and configuration audits in OneinStack production environments.

These tasks all originated from concrete requirements on actual servers.

For example, after upgrading PHP to 8.5, I needed to continue resolving compatibility issues with Phar, GNU libiconv, and Imagick. Upgrading Nginx involved OpenSSL versions, source origins, and post-compilation verification. Later, I also conducted a comprehensive audit of configurations for PHP-FPM, OPcache, Redis, and RDS.

As these adjustments stabilized, I later applied the same customized OneinStack baseline to another Nginx proxy server that does not run WordPress.

At this point, I felt there was no longer any need to keep these modifications confined to my local repository and scattered blog posts.

So this time, I reorganized the parts that have actually made it into the code and been verified in real production environments, and officially published them on GitHub:

GitHub: shuijingwan/oneinstack-custom

https://github.com/shuijingwan/oneinstack-custom

If there are similar OneinStack production maintenance needs in the future, I plan to continue maintaining the relevant modifications in this repository.

[Figure 1: The publicly available oneinstack-custom repository homepage on GitHub]
[Figure 1: The publicly available oneinstack-custom repository homepage on GitHub]

1. This project is not a rewrite of OneinStack

Before officially publishing the repository, I first needed to answer a question:

What exactly is this project?

If you only look at the previous series of server maintenance records, it is easy to misunderstand it as a server optimization toolkit.

If you only look at the environment where the issues initially appeared, you might think of it as a WordPress operations project.

However, after re-examining the current code, Git history, and the OneinStack upstream, neither description is accurate enough.

A more accurate positioning currently is:

A customized OneinStack branch for long-running production servers, supplementing PHP 8.5 compatible builds and Nginx/OpenSSL updates while preserving upstream operational methods.

In other words, this repository is still fundamentally built on OneinStack.

It does not intend to reimplement what OneinStack already does well.

OneinStack itself already provides many complete capabilities, such as:

  • Installation of components like Nginx, Tengine, OpenResty, PHP, databases, and Redis;
  • install.sh installation process;
  • upgrade.sh component upgrades;
  • vhost.sh;
  • HTTPS and certificate management;
  • Service configuration and management;
  • Backups;
  • PHP extensions;
  • PHP-FPM;
  • OPcache;
  • Basic PHP 8.5 support.

Therefore, I have no need to step away from OneinStack and maintain a completely different server management system.

This customized branch still preserves the original OneinStack directory structure, script entry points, and daily management methods as much as possible.

I only make incremental modifications to specific areas when actual problems are encountered in long-term production environments.

[Figure 2: Project positioning, creation reasons, and relationship with OneinStack in the Chinese README]
[Figure 2: Project positioning, creation reasons, and relationship with OneinStack in the Chinese README]

2. These modifications originally came from real production environment issues

This repository did not start by brainstorming a bunch of “features” and then looking for use cases.

The actual process was exactly the opposite.

Many modifications were accumulated bit by bit while maintaining production servers that had been running for years.

I have previously documented several important processes.

The first part involves the PHP 8.5 upgrade and the subsequent series of compatibility issues:

Records of upgrading PHP 8.5 in a OneinStack production environment

The second part covers the Nginx and OpenSSL upgrades:

Records of upgrading Nginx/OpenSSL in an Alibaba Cloud OneinStack environment

The third part involves the Redis upgrade, along with added backup, verification, and rollback protections for the production environment:

Redis upgrade practices in a OneinStack environment

After that, I conducted a comprehensive audit of the actual running configurations for PHP-FPM, OPcache, Redis, RDS, and more:

Comprehensive audit of PHP-FPM, OPcache, Redis, RDS, and other server configurations

Later, this customized OneinStack baseline was applied to an Nginx proxy node that does not run WordPress:

Previous related record

This step further illustrates one point:

WordPress was the production workload where many issues initially surfaced, but it does not define the boundaries of this repository.

What is actually being modified and maintained is the following, more fundamental environment:

OneinStack, Linux, PHP, PHP-FPM, Nginx, OpenSSL, as well as component upgrades and compatibility issues in long-term production servers.

3. What is the difference between the native OneinStack solution and this customized branch?

When organizing the public repository this time, I specifically re-compared it against the current official OneinStack implementation.

This was necessary.

As OneinStack itself continues to evolve, some issues I previously had to handle myself may have already been supported upstream.

Without re-comparing, it would be easy to mistakenly claim capabilities that OneinStack already possesses as my own features.

In the end, a comparison table was specifically added to the README.

[Figure 3: Complete comparison table between the native OneinStack solution and oneinstack-custom]
[Figure 3: Complete comparison table between the native OneinStack solution and oneinstack-custom]

The current relationship is quite clear:

Environment installation and daily management

OneinStack already handles Nginx, Tengine, OpenResty, PHP, databases, Redis, virtual hosts, certificates, backups, and common component upgrades.

This branch does not reimplement these capabilities.

It primarily continues to use the existing OneinStack operational methods.

PHP 8.5

OneinStack currently has basic PHP 8.5 support.

Therefore, this repository cannot simply be described as “bringing PHP 8.5 support to OneinStack.”

What it actually adds is some more specific compatibility handling and verification logic that I encountered while upgrading to PHP 8.5.9 in a real production environment.

Imagick

OneinStack already provides a specific Imagick version selection for PHP 8.5.

The current customized branch further pins it to the verified Imagick 3.8.1.

PHP-FPM and OPcache

OneinStack itself can already generate and manage the relevant configurations.

This branch further adds a verified configuration baseline and explicitly checks the PHP-FPM configuration and service status after installation is complete.

Nginx/OpenSSL

OneinStack itself supports building Nginx, Tengine, and OpenResty using a configured OpenSSL source.

The current branch pins the relevant build chain to OpenSSL 3.5.7 and adjusts the installation and upgrade paths to fetch the source code from the official OpenSSL origin.

So what this project actually does is not:

“OneinStack lacks these features, so I reimplemented them.”

It is closer to:

“OneinStack has already solved the basic problems, and I am continuing to solidify the specific issues further encountered in long-term production environments into this branch.”

4. The PHP 8.5 modifications are not just changing a version number

This is also one of the reasons I felt it was necessary to publish the code.

If you only read the blog, it is easy to think:

PHP 8.5.9, Imagick 3.8.1, OpenSSL 3.5.7—these are just a matter of changing a few version numbers.

In reality, that is not the case.

During the actual build process for PHP 8.5, I encountered a GNU libiconv header file conflict.

The handling approach that ultimately made it into the repository involves identifying before building:

/usr/local/include/iconv.h

If a conflict exists, this file is temporarily moved.

At the same time, you cannot just simply mv once and be done.

Because if the compilation fails midway, the script exits, or a termination signal is received, the original file should still be restored.

Therefore, a restore function has been added to the script, handled via trap:

  • EXIT
  • INT
  • TERM
  • HUP

This ensures that even if the build process terminates abnormally, the original iconv.h is restored as much as possible.

[Figure 4: Temporary move of iconv.h for PHP 8.5, trap restoration, PHP-FPM verification, and customized versions]
[Figure 4: Temporary move of iconv.h for PHP 8.5, trap restoration, PHP-FPM verification, and customized versions]

The handling of PHP-FPM is similar.

The script does not merely execute a start operation and then assume everything is fine.

It now continues to check:

  • Whether PHP-FPM can restart normally;
  • Whether the service is in an active state;
  • Whether it exits explicitly on error, rather than continuing to report the entire installation process as successful.

The key versions that have currently made it into the repository and are pinned include:

  • PHP 8.5.9;
  • Imagick 3.8.1;
  • OpenSSL 3.5.7.

These are not just for the sake of chasing new versions, but rather combinations actually used and verified in the current production environment.

5. What was done in the blog does not mean everything is automated in the repository

When publishing the repository this time, I felt another important principle was to separate these two things:

What was actually done during the operations process;

and:

What the GitHub repository currently actually implements.

The two are not entirely the same.

For example, during the previous Redis upgrade process, I actually performed:

  • Multi-layer backups;
  • Rollback preparation;
  • Kernel parameter tuning;
  • Temporary port testing;
  • Post-upgrade status verification.

However, these processes have not yet been fully automated into oneinstack-custom.

Similarly:

  • Complete Nginx side-channel build and automatic rollback;
  • Independent configuration audit commands;
  • Dynamic parameter tuning for PHP-FPM, Redis, and RDS;
  • Application-level acceptance for WordPress, REST API, caching, etc.;
  • Go Playground proxy;
  • CORS;
  • 8443;
  • Certificate deployment.

These are all tasks I have actually done before, but just because they were documented in the blog does not mean I can directly list them as features already provided by the GitHub repository.

Therefore, the README specifically preserves this boundary.

For example, the Redis entry explicitly states:

Currently, no rollback automation or independent configuration audit commands have been added.

I think this distinction is actually quite important.

After the repository is public, what people really care about is:

What it can actually do right now after downloading the current code.

Not how many things I have manually accomplished in the past.

6. Configuration optimization is not “the larger the parameters, the better”

The previous configuration audits also influenced the subsequent maintenance direction of this repository.

Server optimization can easily turn into a process of “applying parameter templates.”

Online, you can often see various so-called:

  • Best Nginx parameters;
  • Best PHP-FPM parameters;
  • Best Redis configuration;
  • Best OPcache configuration;
  • Best database configuration.

But in a real production environment, there is no fixed set of parameters that applies to all servers.

Differences in machine memory, CPU, traffic, application types, and cache structures naturally mean that the appropriate parameters will also differ.

In the previous actual audits, some parameters were indeed ultimately adjusted.

But there were also many parameters where, after considering server resources, logs, and real running states, the final choice was:

To leave them unchanged.

So if I continue to expand this repository in the future, I prefer to stick to this direction:

Only modifications supported by real issues and actual evidence should enter the customized branch.

Rather than adding a large number of unverified so-called best parameters just to make the README look like it has more “optimization items.”

7. Why keep the original OneinStack operational methods

Since I have already made my own customized branch, there is another question:

Why not just rewrite all the various processes from scratch?

One very practical reason is that OneinStack has been running for years and has accumulated a lot of mature installation and management logic.

In my own production environment, I have also long been accustomed to its directory and management methods.

Therefore, the current principle remains:

For any operation where OneinStack already provides an official script or native management process, prioritize continuing to use the original solution.

Additional handling is only added when the original process truly cannot fully cover actual requirements.

This also means that when syncing OneinStack upstream updates in the future, you cannot simply overwrite directly.

The upstream baseline adopted by the current repository is the OneinStack commit:

42d59b3

This repository is also not an automatic upstream-tracking mirror.

If there are new OneinStack commits to sync in the future, you should still read the diffs first and then consciously merge them.

A rather important warning was also specifically added to the README:

./upgrade.sh --oneinstack

It will overwrite the current customized branch with the upstream release package, so it cannot be executed casually as a normal component upgrade command.

For a OneinStack environment with local customizations, this point is quite important.

8. Another round of complete checks before making it public on GitHub

Since I was preparing to make the repository public, I could not just run git push once.

Before the official release this time, I re-checked:

  • README;
  • Chinese README;
  • Git history;
  • Current working tree;
  • .gitignore;
  • License;
  • Script syntax;
  • External links;
  • Authentication credentials;
  • High-risk information in historical commits.

This check did not find any real passwords, tokens, API keys, private keys, bearer tokens, or other authentication secrets.

At the same time, .gitignore was added to prevent some sensitive files generated during actual production runs from being accidentally committed in the future.

Something worth noting here is:

tools/iplist.txt

It may save remote host passwords during the remote backup process, so it has been explicitly added to the ignore list.

The repository continues to use the original Apache License 2.0.

9. 110 Shell scripts and entry points all pass syntax checks

This repository itself does not have an independent test suite, nor does it have additional lint configurations.

So before making it public this time, I at least ran another round of Bash syntax checks on all current Shell scripts and entry points.

The repository currently contains:

  • 109 .sh files;
  • 1 init.d/Tomcat-init without the .sh suffix, but which is actually a Shell entry point.

A total of 110 Shell scripts/entry points.

Ultimately, all passed:

bash -n

checks.

[Figure 5: 110 Shell scripts/entry points passing bash -n, while also showing the final commit and Git status]
[Figure 5: 110 Shell scripts/entry points passing bash -n, while also showing the final commit and Git status]

This round of public organization ultimately contains two commits:

55de35b

chore: 完成 OneinStack 定制分支公开整理

and:

cb6f0dc

chore: 忽略备份流程运行时敏感文件

Final HEAD:

cb6f0dc11881b15c76ef821be8303adef8c88ada

Local status is:

YAML
## main...origin/main

That is to say, the local main and the GitHub origin/main are now consistent, and the working tree is clean.

10. Why make it public now

From my own perspective, this repository will still primarily serve my own production servers going forward.

But since many of these issues are problems that OneinStack users might encounter after maintaining servers for a long time, continuing to keep them only locally offers limited value.

Especially as fundamental components like PHP, Nginx, and OpenSSL continue to update, some build processes that previously had no issues might develop new compatibility boundaries after a few years.

By making it public on GitHub, at least these modifications can:

  • Have a complete Git history;
  • Allow viewing specific diffs;
  • Be continuously compared with the OneinStack upstream;
  • Have issues recorded via Issues;
  • Accept compatibility feedback from different environments;
  • Gradually solidify truly stable manual operations processes into code.

For readers who have similar long-term OneinStack production environment maintenance needs, if the handling methods in the current repository offer reference value, you can Star it on GitHub.

This will make it easier to look up these modifications again later or follow future updates.

Repository address:

https://github.com/shuijingwan/oneinstack-custom

11. What will continue to be done next

Currently, I do not plan to immediately script all past manual operations just to give the repository “more features.”

The next step is more likely to continue following the current principle:

Actual use → Discover issues → Complete verification → Confirm the solution is stable → Then decide whether it enters the repository.

For example, if the Redis upgrade, backup, and rollback processes eventually form a sufficiently stable and universal automated solution, I will then consider adding them to this branch.

The same goes for configuration audits.

Rather than directly adding a bunch of so-called optimization parameters, I prefer to gradually distill the following in the future:

  • Why check;
  • Based on what to judge;
  • Under what circumstances it should be modified;
  • Under what circumstances it should not be modified;
  • How to verify after modification;
  • How to recover if something goes wrong.

This way, this repository will not slowly turn into another unmaintainable “heavily modified installation script.”

It is more suitable as a:

OneinStack customized branch that evolves following real production requirements over the long term.

This is also the main reason I decided to officially publish oneinstack-custom on GitHub this time.

关于作者 · 持续学习与技术实践

我是一名拥有 15 年以上开发经验的技术从业者,自 2013 年起持续运营个人技术博客,记录工作与个人项目中遇到的真实问题,以及解决问题过程中的探索、实践和思考。

除了技术写作,我也在持续开发和维护自己的独立项目,探索新技术和新工具在实际场景中的应用。我始终相信,没有不值得去解决的问题,也没有不值得去学习的技术。

如果这篇文章对你有所帮助,欢迎浏览博客中的其他文章,也欢迎交流技术经验与想法。

关于我  ·  GitHub  ·  邮件联系