Ubuntu 22.04 安装 Atheos v601 指南

Ubuntu 22.04 + Apache2 + PHP 8.1 从零安装 Atheos v601 实测：git clone 与 tar.gz 双方案、Web 初始化、登录与文件管理端到端验证、.htaccess 安全项实测对照与排障 FAQ。

AtheosAtheosUbuntu 22.04PHP2026/10/27

Ubuntu 22.04 安装 Atheos v601 指南

目标：在一台 Ubuntu 22.04 服务器上从零完成 Atheos v601（Apache2 + PHP 8.1）的安装、初始化与功能验证，含在线/离线两种安装方案、安全项配置与排障实录。本文全部命令与回显已在 Ubuntu 22.04.5 LTS（x86_64）真实环境实测通过（实测日期 2026-10-27）。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Web 服务器：Apache/2.4.52（Ubuntu 官方源）
  • PHP：8.1.2-1ubuntu2.28（Ubuntu 22.04 默认源，libapache2-mod-php）
  • Atheos 版本：v601（2025-01-10 发布，本文实测的最新稳定版）
  • 部署路径：/var/www/html（Apache 默认 DocumentRoot）
  • 监听端口：80（HTTP）
  • 演示账号：admin / q1w2e3r4（初始化向导中创建）

二、前置条件

开始安装前确认以下条件，逐条实测核对：

  1. 一台已就绪的 Ubuntu 22.04 服务器，具备 root 或 sudo 权限。
  2. 服务器可访问软件源（archive.ubuntu.com）——安装 Apache/PHP 依赖需要。
  3. 下载 Atheos 源码需要能访问 GitHub。⚠️ 网络说明：本文实测时 GitHub 官方源直连失败（curl 连接超时，exit 7），已改用代理通道完成下载；两种方案下文均给出实测可用的下载命令。如你的网络可直连 GitHub，去掉代理参数即可。
  4. 80 端口未被其他服务占用。

更新软件源索引（实测回显节选）：

apt-get update

Get:6 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 Packages [4759 kB]
Get:7 http://security.ubuntu.com/ubuntu jammy-security/main amd64 Packages [4430 kB]
Get:8 http://archive.ubuntu.com/ubuntu jammy-updates/universe amd64 Packages [1628 kB]
Fetched 12.5 MB in 5s (2573 kB/s)
Reading package lists...

三、版本选型说明

Atheos 的版本号在 v5.5.0 之后改为纯数字形态（v601），主分支 .version 文件实时递增（查询时为 611，即下一个开发版本）。发行版与运行环境对照（来源：GitHub Releases/Tags 页、官方 Dockerfile、v601 Release Notes，查询日期 2026-10-27）：

版本发布日期说明
v601（本文选用）2025-01-10最新稳定版；集中修复认证后路径穿越等关键安全漏洞（官方标注 "highly recommended for all users"），含 PHP 8 兼容性修复
v5.5.02022-10-05上一代稳定版，含已知安全漏洞，不建议新装
main 分支（611+）滚动开发开发线，官方 Docker 镜像按 main 每次提交自动构建

PHP 版本兼容性矩阵（实测 + 官方证据）：

PHP 版本兼容性依据
7.4官方基线支持官方 Docker 镜像 hlsiira/atheos 内置 PHP 7.4
8.1（本文实测）实测可用Ubuntu 22.04 默认源 PHP 8.1.2 + v601 全流程实测通过
8.2+预期兼容v601 含 "PHP8 basic fixes"（#294）与 "Fix/file paths and php 8"（#260）

💡 选型结论：新装一律选 v601（安全修复是硬理由）；PHP 直接用 Ubuntu 22.04 官方源的 8.1 即可，无需额外 PPA。

四、在线安装方案（A：git clone 官方仓库）

本方案用 git 直接从官方仓库克隆 v601 标签，适合网络通畅、需要后续用 git 追踪版本的服务器。

4.1 方案说明

官方安装文档（docs/installation/ubuntu.md）推荐的标准形态：Apache2 + PHP + git clone 到 /var/www/html。优点是以后可以用 git fetch --tags 精确切换版本；缺点是要求服务器能访问 GitHub。

4.2 安装 Apache 与 PHP 依赖

安装 Apache、PHP（含 Atheos 必需的 zip/mbstring 扩展）与 git（实测回显节选）：

DEBIAN_FRONTEND=noninteractive apt-get install -y apache2 php libapache2-mod-php php-zip php-mbstring php-xml php-curl git unzip curl

Processing triggers for php8.1-cli (8.1.2-1ubuntu2.28) ...
Processing triggers for libapache2-mod-php8.1 (8.1.2-1ubuntu2.28) ...

验证三件套版本与必需扩展（实测回显）：

php -v
apache2 -v
git --version
php -m | grep -iE "zip|mbstring|openssl|curl|xml"

PHP 8.1.2-1ubuntu2.28 (cli) (built: Oct 19 2026 18:54:45) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
    with Zend OPcache v8.1.2-1ubuntu2.28, Copyright (c), by Zend Technologies
---
Server version: Apache/2.4.52 (Ubuntu)
---
git version 2.34.1
---
curl
mbstring
openssl
SimpleXML
xml
zip

Atheos 安装向导硬性检查 ZIP/OpenSSL/MBString 三个扩展（源码 components/install/view.php 中 extension_loaded 检查），上面回显确认三者全部就绪。

4.3 下载 Atheos v601 源码（git clone）

清空默认站点目录并克隆 v601 标签。⚠️ 网络说明：本文实测 GitHub 直连不可用，git 走了代理（git config --global http.proxy）；网络可直连的服务器省略两条 proxy 配置。

git config --global http.proxy http://192.168.1.62:7897
git config --global https.proxy http://192.168.1.62:7897
rm -rf /var/www/html/*
git clone --depth 1 --branch v601 https://github.com/Atheos/Atheos.git /var/www/html

实测 1.8 秒完成克隆。验证版本号文件（实测回显）：

cat /var/www/html/.version

{"version":601}

⚠️ 注意：git clone 方式会把 .git 目录带进站点根目录，生产环境建议在 Apache 配置中拒绝 .git 路径访问（见九、配置说明的安全项），或改用方案 B 的 tar.gz（天然不含 .git）。

4.4 权限设置与 Apache 配置

Atheos 是纯 PHP 平面文件应用，Web 服务器需要对 config.php、data/、workspace/、plugins/、theme/ 有写权限；同时其自带的 .htaccess 承担着保护 data/ 等敏感目录的职责，必须让 Apache 允许它生效。

# 站点属主交给 Apache 运行用户
chown -R www-data:www-data /var/www/html

# 开启 rewrite 模块（Atheos 路由需要）
a2enmod rewrite

# 允许 /var/www 下 .htaccess 生效：把 apache2.conf 中 <Directory /var/www/> 的 AllowOverride None 改为 All
sed -i '170,174s/AllowOverride None/AllowOverride All/' /etc/apache2/apache2.conf
sed -n '170,174p' /etc/apache2/apache2.conf

实测回显：

Enabling module rewrite.
To activate the new configuration, you need to run:
  systemctl restart apache2
<Directory /var/www/>
	Options Indexes FollowSymLinks
	AllowOverride All
	Require all granted
</Directory>

4.5 systemd 托管与启动验证

Ubuntu 官方源的 apache2 包自带 systemd 单元，直接启用并启动：

systemctl enable apache2
systemctl start apache2
systemctl is-active apache2

实测回显：

Synchronizing state of apache2.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable apache2
active

查看运行状态（实测回显节选）：

systemctl status apache2 --no-pager

● apache2.service - The Apache HTTP Server
     Loaded: loaded (/lib/systemd/system/apache2.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-27 09:16:23 UTC; 12min ago
   Main PID: 12347 (apache2)
      Tasks: 6 (limit: 2932)
     Memory: 20.5M

HTTP 层验证（实测回显）：

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost/

HTTP 200

返回 200 且页面标题为 Atheos IDE 即部署成功，接下来转「七、初始化安装」。

五、官方 tar.gz 离线包安装方案（B）

本方案从 GitHub Releases 下载 v601 源码压缩包安装，不带 .git，适合批量分发、内网中转或不想暴露 git 历史的服务器。

5.1 方案说明

GitHub 对每个标签自动生成源码归档包 https://github.com/Atheos/Atheos/archive/refs/tags/v601.tar.gz。解压即得纯净源码树，是离线/半离线环境的首选。

5.2 依赖安装

与方案 A 的 4.2 完全相同（Apache + PHP + 扩展），不再重复，照做即可。

5.3 下载并解压 v601 源码包

⚠️ 网络说明：实测官方源直连失败（curl exit 7 连接超时），走代理 1.6 秒完成下载；可直连环境去掉 -x 参数。

cd /tmp
curl -sL -x http://192.168.1.62:7897 -o atheos-v601.tar.gz https://github.com/Atheos/Atheos/archive/refs/tags/v601.tar.gz
ls -la atheos-v601.tar.gz
sha256sum atheos-v601.tar.gz

实测回显：

-rw-r--r-- 1 root root 3754856 Oct 27 09:15 atheos-v601.tar.gz
509cbe70b1a614fa0107156619802ff7f7cb1975eaa73a5078c22f2334675f93  atheos-v601.tar.gz

包大小 3.75 MB。解压并落位到站点目录：

tar -xzf /tmp/atheos-v601.tar.gz -C /tmp/
rm -rf /var/www/html/*
mv /tmp/Atheos-601/* /tmp/Atheos-601/.[!.]* /var/www/html/
cat /var/www/html/.version

实测回显：

{"version":601}

5.4 权限、Apache 配置与启动

与方案 A 的 4.4、4.5 完全相同（chown www-data、a2enmod rewrite、AllowOverride All、systemctl enable/start），照做即可。

六、方案对比与选择建议

维度方案 A：git clone方案 B：tar.gz 离线包
版本v601（同）v601（同）
是否需联网需要（克隆时）仅需一次性取包，可内网中转
站点目录内容含 .git（需额外防护）纯净源码树
后续升级git fetch --tags && git checkout重新下载新包覆盖
适合场景需要跟踪上游、频繁升级生产固化、内网分发

选择建议：生产服务器优先方案 B（目录干净、不含 git 历史）；开发/跟随上游场景选方案 A。两方案在「初始化安装」之后的步骤完全一致。

七、初始化安装（Web 安装向导）

无论哪种方案，落位后浏览器打开 http://<服务器IP>/ 会进入 Atheos 初始化向导（Initial Setup）：依次填写管理员用户名、密码、首个项目名、时区并提交。向导提交的本质是向 components/install/process.php 发一个 POST。下面给出等价的命令行实测（与浏览器表单完全同一接口），便于无法立即开浏览器的场景：

curl -s -X POST http://localhost/components/install/process.php \
  -d "username=admin" \
  -d "password=q1w2e3r4" \
  -d "projectName=demo" \
  -d "timezone=Asia%2FShanghai" \
  -d "development=false" \
  -d "analytics=false" \
  -H "Accept-Language: zh-CN" -w "\nHTTP %{http_code}\n"

实测回显：

{"username":"admin","lastLogin":"2026-10-27 09:16:48","text":"Installation successful.","status":200}
HTTP 200

初始化完成后系统自动生成三样东西（实测回显）：

ls /var/www/html/data/ /var/www/html/workspace/

/var/www/html/data/:
README.md
analytics.db.json
cache
projects.db.json
users.json

/var/www/html/workspace/:
README.md
demo
  • config.php：站点主配置（BASE_URL/时区/安全响应头等，详见《Atheos v601 配置参数详解》篇）；
  • data/users.json：账号库（admin 的 bcrypt 密码哈希）；
  • workspace/demo/：首个项目目录。

⚠️ 注意：config.php 中的 BASE_URL 取自安装时请求的 Host 头。用 http://localhost/ 完成初始化，BASE_URL 就是 localhost；生产环境请直接用最终对外地址（如 http://192.168.1.100 或域名）打开向导，避免后续回跳链接异常。

八、功能验证

初始化完成后做一次「登录 → 建文件 → 写内容 → 读回」的端到端验证，确认账号、会话、文件读写全链路可用。以下接口就是前端实际调用的服务端接口，逐条实测。

8.1 登录认证

curl -s -c /tmp/atheos-cookie -X POST "http://localhost/controller.php" \
  -d "target=user&action=authenticate&username=admin&password=q1w2e3r4&language=zh" -w "\nHTTP %{http_code}\n"

实测回显：

{"username":"admin","lastLogin":false,"text":"Successfully authenticated.","status":200}
HTTP 200

8.2 新建源文件

curl -s -b /tmp/atheos-cookie -X POST "http://localhost/controller.php" \
  -d "target=filemanager&action=create&path=demo/hello.php&type=file"

实测回显：

{"modifyTime":1793092724,"status":200}

8.3 写入并保存内容

curl -s -b /tmp/atheos-cookie -X POST "http://localhost/controller.php" \
  --data-urlencode 'content=<?php echo "Hello Atheos";' \
  -d "target=filemanager&action=save&path=demo/hello.php"

实测回显：

{"modifyTime":1793092724,"status":200}

8.4 读回文件与磁盘核对

curl -s -b /tmp/atheos-cookie -X POST "http://localhost/controller.php" \
  -d "target=filemanager&action=open&path=demo/hello.php"
cat /var/www/html/workspace/demo/hello.php

实测回显：

{"content":"<?php echo \"Hello Atheos\";","modifyTime":1793092724,"status":200}
<?php echo "Hello Atheos";

接口读回内容与磁盘文件逐字一致，文件由 www-data 属主写入，全链路验证通过。浏览器打开 http://<服务器IP>/ 用 admin / q1w2e3r4 登录即可看到 demo 项目与 hello.php。

九、配置说明

安装后需要立即关注两类配置：Atheos 主配置与 Apache 安全项。

9.1 主配置 config.php（要点速览）

初始化向导自动写入 /var/www/html/config.php，核心项实测值：

define("BASE_PATH", __DIR__);                  // Atheos 根目录
define("BASE_URL", "localhost");               // 对外访问地址（安装时 Host 头决定）
define("TIMEZONE", "Asia/Shanghai");           // 时区
define("DEVELOPMENT", false);                  // 开发模式开关
define("LIFETIME", false);                     // 会话有效期（秒），false=浏览器会话

完整参数逐项含义、数据文件结构与 php.ini 关联项见《Atheos v601 配置参数详解》篇，本文不展开。

9.2 Apache 安全项：必须让 .htaccess 生效（含实测对照）

Atheos 自带的 /var/www/html/.htaccess 是敏感数据的唯一访问屏障，关键规则：

RedirectMatch 403 ^/data/*$
<Files ~ "^.*\.(txt|yml|md|xml|json)">
  Require all denied
</Files>

Ubuntu 默认 AllowOverride None 会让它整体失效——账号密码哈希将直接暴露。本文实测对照（同一实例，仅切换 AllowOverride）：

# AllowOverride None（默认）时
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/data/users.json
# 200   ← 密码哈希可直接下载，严重泄露

# 改为 AllowOverride All 并重启后
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/data/users.json
# 403   ← 防护生效

⚠️ 注意：部署完成必须实测一次 http://<服务器IP>/data/users.json 返回 403；若返回 200，立即检查 AllowOverride 与 .htaccess 是否被正确读取。方案 A 还应额外封禁 .git 路径，可在站点配置追加 <DirectoryMatch "/\.git"> Require all denied </DirectoryMatch>。

十、常见问题（FAQ）

10.1 下载 GitHub 资源超时失败

Q1： curl/git clone 访问 github.com 长时间无响应或 exit 7（连接失败）怎么办？

实测现象与解决：本文实测环境 GitHub 官方源直连不可用，改用代理后秒级完成（curl -x http://<代理>:<端口>、git config --global http.proxy）。无代理条件时可在畅通网络下载 tar.gz 后用 scp 中转进内网服务器，走方案 B 离线安装。

10.2 初始化向导提示依赖未满足

Q2： 打开安装页时向导红色告警无法提交怎么办？

向导只硬性检查 ZIP / OpenSSL / MBString 三个 PHP 扩展（components/install/view.php 实测源码）。用 php -m | grep -iE "zip|mbstring|openssl" 核对，缺哪个装哪个：apt-get install -y php-zip php-mbstring（openssl 由 PHP 核心自带），然后 systemctl restart apache2。

10.3 data/users.json 可以直接下载

Q3： 浏览器访问 http://<IP>/data/users.json 返回 200 并显示密码哈希？

这是 Apache 未放行 .htaccess 的典型症状（实测见 9.2 节）。修改 /etc/apache2/apache2.conf 中 <Directory /var/www/> 段的 AllowOverride None 为 AllowOverride All，systemctl restart apache2 后复测应返回 403。

10.4 升级版本的方法

Q4： 后续如何升级到新版 Atheos？

官方无自动升级（README 明确说明）。保留 config.php、data/、workspace/、plugins/、theme/，其余用新版文件覆盖；方案 A 也可 git fetch --tags && git checkout <新标签>。升级前务必备份上述五项。

十一、卸载与清理

Atheos 无系统级安装痕迹，删除站点目录并清理 Apache/PHP 即可：

# 1. 停止并移除站点
systemctl stop apache2
rm -rf /var/www/html/*

# 2. 如需彻底移除 Apache/PHP（确认无其他站点再用）
apt-get purge -y apache2 php libapache2-mod-php php-zip php-mbstring php-xml php-curl
apt-get autoremove -y

# 3. 清理下载的源码包
rm -f /tmp/atheos-v601.tar.gz

十二、参考链接