Nextcloud AppAPI Docker Socket Proxy

这是一个针对AppAPI的Docker Socket安全增强代理。它内置身份验证和严格的暴力破解防护。指定AppAPI允许使用哪些Docker API的规则与Nextcloud AIO中的规则相同。

When to use

我们强烈建议在所有情况下使用它，除了Nextcloud AIO，在这种情况下应使用标准的Nextcloud AIO Docker Socket代理。

[!IMPORTANT] 重要的是要理解，如果在不受信任的网络上的远程守护进程上安装ExApps，您应始终将此Docker socket代理与TLS一起使用。

How to use

Docker in trusted network

docker run -e NC_HAPROXY_PASSWORD="some_secure_password" \
-v /var/run/docker.sock:/var/run/docker.sock \
--name nextcloud-appapi-dsp -h nextcloud-appapi-dsp \
--restart unless-stopped --privileged -d ghcr.io/nextcloud/nextcloud-appapi-dsp:release

将some_secure_password替换为您的密码，稍后在创建守护进程时需将此密码提供给AppAPI。

some_secure_password通常Docker中的桥接网络类型属于可信网络。

Docker with TLS

在这种情况下，ExApps将仅映射主机的环回适配器，并且只能通过HaProxy供Nextcloud访问。

docker run -e NC_HAPROXY_PASSWORD="some_secure_password" \
-e BIND_ADDRESS="x.y.z.z"
-v /var/run/docker.sock:/var/run/docker.sock \
-v `pwd`/certs/cert.pem:/certs/cert.pem \
--name nextcloud-appapi-dsp -h nextcloud-appapi-dsp --net host \
--restart unless-stopped --privileged -d ghcr.io/nextcloud/nextcloud-appapi-dsp:release

这里，我们额外将主机上的证书文件映射为HaProxy将使用的SSL证书，并指定使用主机网络。

host您应将BIND_ADDRESS设置为运行ExApps的服务器可接受来自Nextcloud实例请求的IP。

BIND_ADDRESS在使用“host”网络时，这是必要的，以避免占用所有接口，因为ExApp将使用环回适配器。

[!WARNING] 如果证书是自签名的，您需要将它们添加到Nextcloud实例中，以便AppAPI能够识别它们。

AppAPI

• 在AppAPI中从Docker Socket Proxy模板创建守护进程。 Docker Socket Proxy- 填写您在创建容器时使用的密码。

Nextcloud AppAPI Docker Socket Proxy

这是一个安全增强型代理，专门用于 AppAPI 的 Docker Socket。

它内置了身份验证和严格的暴力破解防护。

指定 AppAPI 允许使用哪些 Docker API 的规则与 https://github.com/nextcloud/all-in-one/tree/main/Containers/docker-socket-proxy 中的规则相同。

何时使用

我们强烈建议在所有情况下使用它，除了Nextcloud AIO，在这种情况下应使用标准的 Nextcloud AIO Docker Socket 代理。

[!IMPORTANT] 重要的是要理解，如果在不受信任的网络上的远程守护进程上安装 ExApps，则应始终将此 Docker Socket 代理与 TLS 一起使用。

如何使用

可信网络中的 Docker

docker run -e NC_HAPROXY_PASSWORD="some_secure_password" \
-v /var/run/docker.sock:/var/run/docker.sock \
--name nextcloud-appapi-dsp -h nextcloud-appapi-dsp \
--restart unless-stopped --privileged -d ghcr.io/nextcloud/nextcloud-appapi-dsp:release

将 some_secure_password 替换为您的密码，稍后在创建守护进程时需要将此密码提供给 AppAPI。

[!NOTE] 通常 Docker 中的bridge网络类型属于可信网络。

使用 TLS 的 Docker

在这种情况下，ExApps 将仅映射主机的环回适配器，并且只能通过 HaProxy 供 Nextcloud 访问。

docker run -e NC_HAPROXY_PASSWORD="some_secure_password" \
-e BIND_ADDRESS="x.y.z.z"
-v /var/run/docker.sock:/var/run/docker.sock \
-v `pwd`/certs/cert.pem:/certs/cert.pem \
--name nextcloud-appapi-dsp -h nextcloud-appapi-dsp --net host \
--restart unless-stopped --privileged -d ghcr.io/nextcloud/nextcloud-appapi-dsp:release

此外，我们还将主机上的证书文件映射到容器中，该 SSL 证书将由 HaProxy 使用，并指定使用 host 网络。

您应将 BIND_ADDRESS 设置为运行 ExApps 的服务器可接受来自 Nextcloud 实例请求的 IP。

这在使用“host”网络时是必要的，以避免占用所有接口，因为 ExApp 将使用环回适配器。

[!WARNING] 如果证书是自签名的，您需要将它们添加到 Nextcloud 实例中，以便 AppAPI 能够识别。

AppAPI

1. 在 AppAPI 中从 Docker Socket Proxy 模板创建守护进程。
2. 填写您在创建容器时使用的密码。

其他支持的变量

HAPROXY_PORT：使用自定义端口代替默认的 2375。

BIND_ADDRESS：用于端口绑定的地址。（通常仅在远程安装时需要，必须可从 Nextcloud 访问）

TIMEOUT_CONNECT：连接到 ExApp 的超时时间，默认：30s

TIMEOUT_CLIENT：NC 开始向 ExApp 发送请求数据的超时时间，默认：30s

TIMEOUT_SERVER：ExApp 开始响应 NC 请求的超时时间，默认：1800s

NC_AUTOSTART_CONTAINERS：如果设置，将自动启动受管理的应用容器（对 Podman 用户有用）

NC_HAPROXY_PASSWORD_FILE：指定包含 HAProxy 密码的文件路径。

[!NOTE] 此文件应挂载到容器中，密码将从该文件读取。如果同时指定了 NC_HAPROXY_PASSWORD 和 NC_HAPROXY_PASSWORD_FILE，容器将退出并显示错误。

仅适用于使用 TLS 的 ExApp 安装：

• EX_APPS_NET：确定 HaProxy 对 ExApps 请求的目标。默认：localhost

• EX_APPS_COUNT：确定 HaProxy 为代理 ExApps 请求而打开的端口数量。默认：30

在不同主机上运行的示例

当 docker-socket-proxy 安装在与 Nextcloud 不同的主机上时，可以将以下设置与 TLS 配置一起使用。确保防火墙已为端口 2375、23000-230xx（参见 EX_APPS_COUNT）开放。

-e BIND_ADDRESS="xxx.xxx.xxx.xx" 这需要是主机的公网 IP

-e EX_APPS_NET="ipv4@127.0.0.1" 使 HaProxy 能够访问子容器所需

--net: host

开发

HTTP（本地）

要在本地构建镜像，请使用：

docker build -f ./Dockerfile -t nextcloud-appapi-dsp:latest ./

Podman

podman build --format=docker -f ./Dockerfile -t nextcloud-appapi-dsp:latest ./

部署镜像（适用于 nextcloud-docker-dev）：

docker run -e NC_HAPROXY_PASSWORD="some_secure_password" \
-v /var/run/docker.sock:/var/run/docker.sock \
--name nextcloud-appapi-dsp -h nextcloud-appapi-dsp --net master_default \
--privileged -d nextcloud-appapi-dsp:latest

之后，在 AppAPI 中从 Docker Socket Proxy 模板创建守护进程，指定：

1. 主机：nextcloud-appapi-dsp:2375
2. 部署配置中的网络等于 master_default
3. 部署配置：HaProxy 密码：some_secure_password

HTTPS（远程）

我们将使用 nextcloud-docker-dev 环境模拟远程部署。为此，我们将 nextcloud-appapi-dsp 部署到主机网络，并使用 host.docker.internal 访问它。

[!NOTE] 由于当前 Docker 的限制，此设置类型在 macOS 上无法工作。参考问题：https://github.com/docker/roadmap/issues/238

首先为测试创建自签名证书：

openssl req -nodes -new -x509 -subj '/CN=host.docker.internal' -sha256 -keyout certs/privkey.pem -out certs/fullchain.pem -days 365000
> /dev/null 2>&1

cat certs/fullchain.pem certs/privkey.pem | tee certs/cert.pem
> /dev/null 2>&1

将 cert.pem 放入 nextcloud-docker-dev 的 data/shared 文件夹中，并在 Nextcloud 容器内执行：

sudo -u www-data php occ security:certificates:import /shared/cert.pem

创建 HaProxy 容器：

docker run -e NC_HAPROXY_PASSWORD="some_secure_password" \
-e BIND_ADDRESS="172.17.0.1" \
-v /var/run/docker.sock:/var/run/docker.sock \
-v `pwd`/certs/cert.pem:/certs/cert.pem \
--name nextcloud-appapi-dsp -h nextcloud-appapi-dsp --net host \
--privileged -d nextcloud-appapi-dsp:latest

Podman 无 root 模式

当 Nextcloud 安装在 Docker 中（例如），且 DSP 将在 Podman 的主机网络上运行时，可使用此模式。

podman run -e NC_HAPROXY_PASSWORD="some_secure_password" \
-e BIND_ADDRESS="172.17.0.1" \
-v /run/user/1000/podman/podman.sock:/var/run/docker.sock \
-v `pwd`/certs/cert.pem:/certs/cert.pem \
--name nextcloud-appapi-dsp -h nextcloud-appapi-dsp --net host \
--privileged -d nextcloud-appapi-dsp:latest

之后，从 Docker Socket Proxy 模板在 AppAPI 中创建守护进程，并使用以下参数：

1. 主机：host.docker.internal:2375
2. 勾选 https 复选框。
3. 部署配置：HaProxy 密码：some_secure_password

已知问题

IPv6 支持

[!NOTE] 仅当运行 ExApps 的远程机器默认使用 IPv6 协议时才需要此项

目前，并非所有外部应用都支持 IPv6 协议，大多数情况下它们仅监听 IPv4。因此，在使用 HTTPS 且 HaProxy 转发传入连接时，创建容器时应额外指定 EX_APPS_NET 变量：

-e EX_APPS_NET="ipv4@localhost"

响应缓慢的 ExApps

某些 AI 应用的响应时间可能长于 HaProxy 配置中定义的标准 30 秒超时。

此类应用的示例：context_chat

为确保此类应用正常运行，可在创建 DSP 容器时通过环境变量设置自定义配置值：

-e TIMEOUT_SERVER="1800s"