Atheos v601 Docker Compose 部署指南

Docker Compose 部署 Atheos v601 实测：官方 latest 镜像（PHP 7.4/开发线）与自建钉版镜像（PHP 8.1/v601）选型对照、四挂载持久化、controller.php 网关登录验证与 .htaccess 安全实测。

AtheosAtheosDockerDocker Compose2026/10/27

Atheos v601 Docker Compose 部署指南

目标：用一份 docker-compose.yml 在 Linux 主机上把 Atheos v601（PHP 8.1 + Apache）跑起来，完成初始化、登录验证与数据持久化核对。本文全部命令与回显已在 Ubuntu 26.04.1 LTS（x86_64）+ Docker 29.9.2 实测通过（实测日期 2026-10-27），演示账号 admin / q1w2e3r4。

一、环境信息

  • 宿主机：Ubuntu 26.04.1 LTS（x86_64），Docker Engine 29.9.2，Docker Compose v5.6.1
  • 应用镜像：atheos:v601（基于 php:8.1-apache 自建钉版镜像，792MB；PHP 8.1.34 + Apache/2.4.65）
  • Atheos 版本：v601（2025-01-10 发布，容器内 .version 文件实测为 {"version":601}）
  • Compose 项目名：atheos-v601-stack（显式 name: 声明，防并行环境互删）
  • 端口映射：宿主机 8130 → 容器 80（HTTP）
  • 持久化：宿主机 ./data、./workspace 两个目录 + config.php、php.ini 两个文件挂载

二、镜像选型说明

Atheos 有官方 Docker Hub 镜像，但实测后推荐自建钉版镜像，对照如下（查询/实测日期 2026-10-27）：

维度官方镜像 hlsiira/atheos:latest自建镜像 atheos:v601（本文方案）
可用标签仅 latest 一个标签（实查 Docker Hub API）自定义，本文钉 v601
构建来源GitHub Actions 每次 push 到 main 自动构建推送（仓库 .github/workflows/docker-build.yml 实证）本地 Dockerfile，源码钉死 v601 tag
镜像内 PHP 版本PHP 7.4.33（实测 php -v 回显）PHP 8.1.34（实测回显）
对应代码线main 开发线（.version 为 611，非稳定发布）v601 稳定发布（2025-01-10）
镜像体积718MB792MB

⚠️ 注意：官方镜像只发 latest、跟随 main 分支滚动构建，且基座仍是 PHP 7.4（官方支持已 EOL）；要部署稳定发布版 v601 并获得 PHP 8.1 运行时，自建钉版镜像是目前唯一可靠途径。下文部署步骤按自建方案展开，仅需官方镜像时可直接把 compose 中 image: 换成 hlsiira/atheos:latest（功能验证步骤相同）。

自建镜像实测回显（容器内）：

$ docker exec atheos-v601-web cat /var/www/html/.version
{"version":601}
$ docker exec atheos-v601-web php -v | head -1
PHP 8.1.34 (cli) (built: Dec 29 2025 23:35:29) (NTS)
$ docker exec atheos-v601-web apache2 -v | head -1
Server version: Apache/2.4.65 (Debian)

三、前置条件

  • Docker Engine ≥ 24 与 Docker Compose v2（本文实测 29.9.2 / v5.6.1）： 
    $ docker version --format 'Server: {{.Server.Version}}'
Server: 29.9.2
$ docker compose version
Docker Compose version v5.6.1
  • 宿主机 8130 端口空闲（ss -ltn | grep 8130 无输出）；占用则改 compose 端口映射
  • 磁盘余量 ≥ 2GB（镜像 792MB + 构建中间层）
  • 构建镜像需访问 GitHub（下载 v601 源码包）；网络受限时走代理，见「十、常见问题」Q1

四、部署步骤

4.1 准备项目目录

mkdir -p /opt/atheos-v601 && cd /opt/atheos-v601
mkdir -p data workspace   # 持久化目录，属主后续由容器内 www-data 接管

4.2 编写 Dockerfile 并构建钉版镜像

Dockerfile（钉死 v601 源码包，补 zip 扩展，开启 Apache rewrite 与 .htaccess）：

FROM php:8.1-apache

# Atheos 必需扩展：zip / mbstring / openssl（官方 php 镜像已内置 mbstring/openssl，补 zip）
RUN apt-get update \
 && apt-get install -y --no-install-recommends libzip-dev unzip git \
 && docker-php-ext-install zip \
 && rm -rf /var/lib/apt/lists/*

# 钉版：官方 v601 源码包（2025-01-10 发布）
ADD https://github.com/Atheos/Atheos/archive/refs/tags/v601.tar.gz /tmp/atheos-v601.tar.gz
RUN tar -xzf /tmp/atheos-v601.tar.gz -C /tmp \
 && cp -r /tmp/Atheos-601/. /var/www/html/ \
 && rm -rf /tmp/atheos-v601.tar.gz /tmp/Atheos-601 \
 && touch /var/www/html/config.php \
 && chown -R www-data:www-data /var/www/html \
 && a2enmod rewrite \
 && sed -i 's/AllowOverride None/AllowOverride All/g' /etc/apache2/apache2.conf

EXPOSE 80

构建并核对：

$ docker build -t atheos:v601 .
# ...（网络下载 v601.tar.gz 后分层构建，全程约 2-4 分钟）
$ docker images atheos:v601 --format '{{.Repository}}:{{.Tag}} {{.Size}}'
atheos:v601 792MB

⚠️ 注意：Dockerfile 中 sed 's/AllowOverride None/AllowOverride All/g' 不可省略——Atheos 用根目录 .htaccess 拦截对 data/、README.md 等敏感路径的直接下载，Apache 默认 AllowOverride None 会让 .htaccess 整体失效（实测对照见「十、常见问题」Q2）。

4.3 准备挂载的配置文件

config.php（Atheos 主配置，完整参数含义见专栏《Atheos v601 配置参数详解》）：

<?php

// PATH TO ATHEOS
define("BASE_PATH", __DIR__);

// BASE URL TO ATHEOS (without trailing slash)
define("BASE_URL", "localhost");

// Add an install domain to the page title
define("DOMAIN", "");
define("THEME", "dark blue");

// SESSION LIFETIME IN SECONDS (e.g. 7200 = 2 hours)
define("LIFETIME", false);

// TIMEZONE
define("TIMEZONE", "Asia/Shanghai");

// DEVELOPMENT MODE
define("DEVELOPMENT", false);

// EXTERNAL AUTHENTICATION
// define("AUTH_PATH", "/path/to/customauth.php");

// SECURITY HEADERS, SET TO FALSE TO DISABLE ALL
define ("HEADERS", serialize(array(
	"Strict-Transport-Security: max-age=31536000; includeSubDomains; preload",
	"X-Frame-Options: SAMEORIGIN",
	"X-XSS-Protection: 1; mode=block",
	"X-Content-Type-Options: nosniff",
	"Referrer-Policy: no-referrer",
	"Feature-Policy: sync-xhr 'self'",
	"Access-Control-Allow-Origin: *"
)));

// ** DO NOT EDIT CONFIG BELOW **

// PATHS
define("COMPONENTS", BASE_PATH . "/components");
define("LIBRARIES", BASE_PATH . "/libraries");
define("PLUGINS", BASE_PATH . "/plugins");
define("DATA", BASE_PATH . "/data");
define("WORKSPACE", BASE_PATH . "/workspace");

define("UPDATEURL", "https://www.atheos.io/update");
define("MARKETURL", "https://www.atheos.io/market/json");
define("GITHUBAPI", "https://api.github.com/repos/Atheos/Atheos/releases/latest");

php.ini（上传到 IDE 的代码文件常超 2MB，务必调大 PHP 上传限制）：

upload_max_filesize = 64M
post_max_size = 64M
memory_limit = 256M
max_execution_time = 120

4.4 编写 docker-compose.yml 并启动

docker-compose.yml：

name: atheos-v601-stack

services:
  atheos:
    image: atheos:v601
    container_name: atheos-v601-web
    hostname: atheos-web
    restart: unless-stopped
    ports:
      - "8130:80"
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./data:/var/www/html/data
      - ./workspace:/var/www/html/workspace
      - ./config.php:/var/www/html/config.php
      - ./php.ini:/usr/local/etc/php/conf.d/atheos.ini:ro

启动与状态核对（实测回显）：

$ docker compose up -d
 Network atheos-v601-stack_default Creating
 Network atheos-v601-stack_default Created
 Container atheos-v601-web Creating
 Container atheos-v601-web Created
 Container atheos-v601-web Starting
 Container atheos-v601-web Started
$ docker compose ps
NAME              IMAGE         COMMAND                  SERVICE   CREATED          STATUS          PORTS
atheos-v601-web   atheos:v601   "docker-php-entrypoi…"   atheos    22 seconds ago   Up 21 seconds   0.0.0.0:8130->80/tcp, [::]:8130->80/tcp
$ curl -s http://localhost:8130/ | grep -oE '<title>[^<]*</title>'
<title>Atheos IDE</title>

4.5 Web 初始化向导

首次访问 http://<宿主机IP>:8130/ 进入安装向导（依赖自检通过后）按表单填写：

  • 用户名：admin，密码：q1w2e3r4（演示账号）
  • 时区：Asia/Shanghai，主题：dark blue
  • 初始项目名：demo（向导会自动在 workspace/ 下建同名目录）

向导字段与逐屏说明同裸机安装一致，见专栏《Ubuntu 22.04 安装 Atheos v601 指南》「七、初始化安装（Web 安装向导）」。

4.6 登录验证（接口级实测）

Atheos 前端所有请求经根目录 controller.php 网关分发（target=组件&action=动作），用 curl 做登录实测：

$ curl -s -c cookies.txt -X POST http://localhost:8130/controller.php \
    -d 'target=user&action=authenticate&username=admin&password=q1w2e3r4'
{"username":"admin","lastLogin":"2026-10-27 17:43:06","text":"Successfully authenticated.","status":200}

返回 status:200 即登录成功，会话 Cookie 写入 cookies.txt，浏览器打开 http://<宿主机IP>:8130/ 即进入 IDE 主界面。

💡 说明：直接 POST /components/user/controller.php 会报 Fatal error: Call to undefined function SESSION()——组件控制器不自带引导，且 .htaccess 本就 403 拦截 /components/*.php 直连，所有调用必须走根 controller.php 网关。

五、数据持久化说明

Atheos 是无数据库的平面文件应用，全部状态落在两个目录，必须持久化：

容器路径内容宿主机挂载
/var/www/html/data用户/项目/会话/日志（JSON 平面文件，含密码 bcrypt 哈希）./data
/var/www/html/workspace用户代码项目文件./workspace

初始化完成后 ./data 实测落盘内容：

$ ls -la data/
drwxr-xr-x 5 www-data www-data 4096 Oct 27 17:43 .
drwxr-xr-x 4 root     root     4096 Oct 27 17:43 ..
-rw-r--r-- 1 www-data www-data  405 Oct 27 17:42 analytics.db.json
drwxr-xr-x 2 www-data www-data 4096 Oct 27 17:42 cache
drwxr-xr-x 2 www-data www-data 4096 Oct 27 17:43 log
-rw-r--r-- 1 www-data www-data   22 Oct 27 17:42 projects.db.json
drwxr-xr-x 2 www-data www-data 4096 Oct 27 17:43 users
-rw-r--r-- 1 www-data www-data  391 Oct 27 18:15 users.json
$ cat data/projects.db.json
{
    "demo": "demo"
}
$ cat data/users.json
{
    "admin": {
        "password": "$2y$10$KDMAMQWs9bLIV9tkEdKIP.S5HcgmuqQub7m9.p9maC7WMb5m38tqW",
        "resetPassword": false,
        "activeProject": "demo",
        "creationDate": "2026-10-27 09:42:55",
        "lastLogin": "2026-10-27 18:15:49",
        "permissions": [
            "configure",
            "read",
            "write"
        ],
        "userACL": "full"
    }
}

⚠️ 注意：挂载目录内文件属主会被容器改为 www-data（uid 33），宿主机直接编辑需 sudo；删除数据须同时清 data/ 与 workspace/，仅删其一会导致登录后项目列表与磁盘不一致。

六、环境变量表

Atheos 本体是 PHP 平面文件应用，不读环境变量做配置（全部应用配置在 config.php，见第七节），compose 中可用环境变量仅有运行时层面的：

变量作用默认值本文取值
TZ容器系统时区（Debian 基座生效）UTCAsia/Shanghai
PHP_UPLOAD_MAX_FILESIZE 等php 基座镜像不支持 env 覆盖 ini，须用挂载 php.ini—见 4.3

💡 技术拓展：与常见的「12-Factor 环境变量配置」应用不同，Atheos（继承自 Codiad）采用「单文件常量配置」模式——define() 常量写在 config.php，运行时 common.php 加载。同类 PHP 应用里，phpList/Mailman 走 ini/php 配置文件，Nextcloud 走 config.php + occ 命令行覆写，Atheos 没有 CLI 覆写通道，改配置=改文件+重启容器（或静置等下次请求，PHP 无状态热读）。

七、配置文件挂载说明

宿主机文件容器路径模式说明
./config.php/var/www/html/config.phprw主配置（初始化向导会回写 BASE_URL 等字段，故不能只读）
./php.ini/usr/local/etc/php/conf.d/atheos.iniroPHP 运行参数，php 基座镜像自动加载 conf.d/*.ini

挂载后容器内实测生效：

$ docker exec atheos-v601-web php -i | grep -E 'upload_max_filesize|memory_limit'
memory_limit => 256M => 256M
upload_max_filesize => 64M => 64M

⚠️ 注意：config.php 不能只读挂载——Web 初始化向导与「系统设置」保存时会回写该文件（如 BASE_URL 按首次访问域名落盘）；只读会导致初始化提交后配置不生效且无明显报错。

八、等价 docker run

不用 Compose 时的等价命令（参数一一对应）：

docker run -d \
  --name atheos-v601-web \
  --hostname atheos-web \
  --restart unless-stopped \
  -p 8130:80 \
  -e TZ=Asia/Shanghai \
  -v /opt/atheos-v601/data:/var/www/html/data \
  -v /opt/atheos-v601/workspace:/var/www/html/workspace \
  -v /opt/atheos-v601/config.php:/var/www/html/config.php \
  -v /opt/atheos-v601/php.ini:/usr/local/etc/php/conf.d/atheos.ini:ro \
  atheos:v601

九、常用运维命令

# 查看日志（Apache access/error 合并输出到 stdout）
docker compose logs -f --tail 100

# 进容器排障
docker exec -it atheos-v601-web bash

# 改 config.php / php.ini 后重启生效
docker compose restart

# 备份（无数据库，两目录即全量）
tar -czf atheos-backup-$(date +%F).tar.gz data/ workspace/ config.php

# 升级到新版（改 Dockerfile 中 tag 后重建并滚动替换）
docker compose up -d --build

十、常见问题

Q1：构建镜像时 ADD https://github.com/... 超时失败？

GitHub 直连不稳定时给 Docker 构建配代理：

docker build --build-arg http_proxy=http://192.168.1.62:7897 \
             --build-arg https_proxy=http://192.168.1.62:7897 \
             -t atheos:v601 .

注意 ADD <URL> 走的是 Docker 守护进程网络，--build-arg 代理对其不生效；守护进程侧需在 /etc/systemd/system/docker.service.d/http-proxy.conf 配代理后 systemctl restart docker。也可先用 curl -L 把 v601.tar.gz 下载到构建目录，把 ADD <url> 改为 COPY atheos-v601.tar.gz /tmp/。

Q2：浏览器直接访问 http://<IP>:8130/data/users.json 能下到用户哈希？

这是 .htaccess 未生效的典型症状（Apache AllowOverride None）。本文 Dockerfile 已 sed 修正，实测防护生效回显：

$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8130/data/users.json
403
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8130/README.md
403

若返回 200，检查镜像是否开启 rewrite 模块与 AllowOverride All（docker exec atheos-v601-web a2query -m rewrite 应回 rewrite (enabled by site administrator)）。

Q3：workspace/ 下的项目文件能被直接访问吗？

分后缀：.htaccess 内置规则拦截 txt|yml|md|xml|json，但 .html/.js/.css 等代码文件可直接匿名下载（实测 workspace/demo/hello.html 返回 200）。公网部署务必在入口加认证（反向代理 Basic Auth）或追加 Apache 加固配置，把 /workspace 整目录拒绝：

<Directory /var/www/html/workspace>
    Require all denied
</Directory>

写入 atheos-harden.conf 后加挂载 - ./atheos-harden.conf:/etc/apache2/conf-enabled/atheos-harden.conf:ro 并 docker compose restart。

Q4：初始化提交后白屏或仍回向导页？

多为 data/ 目录不可写：确认宿主机 ./data 存在且容器内属主为 www-data（docker exec atheos-v601-web ls -la /var/www/html/data）；手工修正 docker exec atheos-v601-web chown -R www-data:www-data /var/www/html/data /var/www/html/workspace。

Q5：官方 hlsiira/atheos:latest 与本文镜像能互换吗？

数据格式兼容（同为 JSON 平面文件），image: 互换后 up -d 即可；但官方镜像为 PHP 7.4 + main 开发线代码（.version 611），与 v601 存在界面/接口差异，生产不建议混用，迁移前按第九节备份。

十一、参考链接

  • GitHub 仓库：https://github.com/Atheos/Atheos（v601 Release：https://github.com/Atheos/Atheos/releases/tag/v601）
  • 官方镜像：https://hub.docker.com/r/hlsiira/atheos；镜像构建仓库：https://github.com/Atheos/Atheos-Docker
  • 官网与文档：https://www.atheos.io、https://github.com/Atheos/Atheos/blob/main/docs/DOCUMENTATION.md
  • 专栏文档：《Atheos v601 介绍与选型指南》《Ubuntu 22.04 安装 Atheos v601 指南》