diff --git a/pages/faq/error.md b/pages/faq/error.md index ebd4c0f44..9c686bb66 100644 --- a/pages/faq/error.md +++ b/pages/faq/error.md @@ -315,3 +315,52 @@ This article will collect some error codes that may occur during the use of Open **A**:可能是因为某些驱动不支持修改文件排序导致的,取消文件排序试试看 ::: + +--- + +::: zh-CN +**Q**:Docker 运行时查看日志,出现: FATA[2025-08-12 02:48:46] failed to create config file: open /opt/openlist/data/config.json: permission denied 。 + +**A**:挂载的目录与运行 Docker 的用户权限不一致导致的。解决方法: + +1. 使用 `--user` 参数来指定运行用户,假设你要运行的用户是 `1000:1000` + + 先确认 `${yourDataDir}` 目录的权限是 `1000:1000`,如果不是,请使用 `sudo chown -R 1000:1000 ${yourDataDir}` 来修改目录权限。 + + 然后使用以下命令运行 Docker: + +```bash +docker run -d --name openlist --user 1000:1000 -v ${yourDataDir}:/opt/openlist/data -p 5244:5244 openlistteam/openlist +``` + +2. 修改 `${yourDataDir}` 目录的拥有者为 `1001:1001`,然后运行 Docker: + +```bash +sudo chown -R 1001:1001 ${yourDataDir} +docker run -d --name openlist -v ${yourDataDir}:/opt/openlist/data -p 5244:5244 openlistteam/openlist +``` + +::: +::: en +**Q**:When running `docker logs openlist`, the error appears: FATA[2025-08-12 02:48:46] failed to create config file: open /opt/openlist/data/config.json: permission denied 。 + +**A**:This is caused by the directory mounted not matching the user permissions running the docker. The solution: + +1. Use the `--user` parameter to specify the user running the container, assuming the user is `1000:1000`. + + First, ensure that the `${yourDataDir}` directory has permissions of `1000:1000`. If not, use `sudo chown -R 1000:1000 ${yourDataDir}` to change the directory permissions. + + Then run the Docker with the following command: + +```bash +docker run -d --name openlist --user 1000:1000 -v ${yourDataDir}:/opt/openlist/data -p 5244:5244 openlistteam/openlist +``` + +2. Change the owner of the `${yourDataDir}` directory to `1001:1001`, and then run the Docker: + +```bash +sudo chown -R 1001:1001 ${yourDataDir} +docker run -d --name openlist -v ${yourDataDir}:/opt/openlist/data -p 5244:5244 openlistteam/openlist +``` + +::: diff --git a/pages/guide/installation/docker.md b/pages/guide/installation/docker.md index 4b863ae7b..3450b2e67 100644 --- a/pages/guide/installation/docker.md +++ b/pages/guide/installation/docker.md @@ -15,11 +15,36 @@ categories: ::: warning It is highly recommended to deploy OpenList in an isolated environment using Docker. Otherwise, without security measures like SELinux or AppArmor, if your password is exposed, and hackers may gain access to all the files on your server. ::: + ::: zh-CN ::: warning 强烈建议使用 Docker 在隔离环境中部署 OpenList。否则,如果没有正确配置像 SELinux 或 AppArmor 这样的安全措施,假如您的密码暴露,黑客将可以访问您服务器上的所有文件。 ::: +::: zh-CN +::: warning + +- 在 `v4.1.0` 以后的版本中(不包含 `v4.1.0`),OpenList 镜像已经移除了 `PUID`、`PGID`,并借鉴于 MariaDB 的构建方式,使用 `useradd` 增加了用户 `openlist`(UID 1001)和组 `openlist`(GID 1001),并使用该用户运行 `openlist server`。 + + 这意味着,您需要手动处理映射的目录的权限问题,确保容器内的 `openlist(1001)` 用户有权限访问映射的目录。 + + 您也可以通过 `--user UID:GID` 的方式来运行容器指定容器内运行 OpenList 的用户和组,让容器内有权限访问映射的目录。 + +- **rootless** 模式中的 Docker, `--user 0:0` 代表当前用户的 UID 和 GID。请确保您在运行容器时,正确设置了 `--user` 参数,以确保文件权限的正确性。 + ::: + +::: en +::: warning + +- In version `v4.1.0` and later (excluding `v4.1.0`), OpenList has removed the `PUID` and `PGID` environment variables in the image, and has adopted a method similar to that of MariaDB, where a user named `openlist` (UID 1001) and a group named `openlist` (GID 1001) are created, and `openlist server` runs under this user. + + This means you need to manually handle the permission issues of the mapped directory, ensuring that the OpenList user (1001) inside the container has access to the mapped directory. + + You can also run the container with the `--user UID:GID` option to specify the user and group under which OpenList runs inside the container, allowing it to access the mapped directory. + +- In the **rootless** mode of Docker, `--user 0:0` represents the current user's UID and GID. Please ensure that you set the `--user` parameter correctly when running the container to ensure proper file permissions. + ::: + ## Install { lang="en" } ## 安装 { lang="zh-CN" } @@ -29,10 +54,59 @@ It is highly recommended to deploy OpenList in an isolated environment using Doc ::: en Install Docker. And run the command below: ::: + ::: zh-CN 安装好 Docker 后,执行以下命令: ::: +#### v4.1.0 以后版本 { lang="zh-CN" } + +#### For version after v4.1.0 { lang="en" } + +::: zh-CN +::: warning +请注意:`/etc/openlist` 仅为默认映射的目录,您可以根据需要修改为其他目录。 +::: + +::: en +::: warning +Please note: `/etc/openlist` is just the default mapped directory, you can change it to another directory as needed. +::: + +::: zh-CN +::: tip +如果您希望使用当前用户运行和管理 OpenList 及其配置目录,请使用以下命令: +::: + +::: en +::: tip +If you are using the current user to run and manage OpenList and its configuration directory, please use the following command: +::: + +```bash +mkdir -p /etc/openlist +docker run --user $(id -u):$(id -g) -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e UMASK=022 --name="openlist" openlistteam/openlist:latest +``` + +::: zh-CN +::: tip +如果您希望使用 1001,即容器内置的默认 `openlist` 用户运行和管理 OpenList 及其配置目录,请使用以下命令: +::: + +::: en +::: tip +If you want to run and manage OpenList and its configuration directory using the default OpenList user (1001) inside the container, please use the following command: +::: + +```bash +sudo chown -R 1001:1001 /etc/openlist +docker run -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e UMASK=022 --name="openlist" openlistteam/openlist:latest +``` + +#### v4.1.0 及以前版本 { lang="zh-CN" } + +#### For version v4.1.0 and earlier { lang="en" } + ```bash docker run -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="openlist" openlistteam/openlist:latest ``` @@ -59,6 +133,30 @@ Write the content below. Then save and exit. 写入以下内容,然后保存并退出: ::: +#### For version after v4.1.0 { lang="en" } + +#### v4.1.0 以后版本 { lang="zh-CN" } + +```yaml +# docker-compose.yml +services: + openlist: + image: 'openlistteam/openlist:latest' + container_name: openlist + user: '0:0' # Please replace `0:0` with the actual user ID and group ID you want to use to run OpenList. + volumes: + - './data:/opt/openlist/data' + ports: + - '5244:5244' + environment: + - UMASK=022 + restart: unless-stopped +``` + +#### For version v4.1.0 and earlier { lang="en" } + +#### v4.1.0 及以前版本 { lang="zh-CN" } + ```yaml # docker-compose.yml services: @@ -95,8 +193,8 @@ docker compose up -d ::: en | Name | Default | Desc | |:------------|:--------|----------------------------------------------------------------------------------------------------------------------------| -| `PUID` | `0` | User UID | -| `PGID` | `0` | User GID | +| `PUID` | `0` | User UID, Deprecated in v4.1.0 later versions| +| `PGID` | `0` | User GID, Deprecated in v4.1.0 later versions| | `UMASK` | `022` | https://en.wikipedia.org/wiki/Umask | | `TZ` | `UTC` | Default is the UTC time zone. If you want to specify a time zone, you can set this variable, for example: `Asia/Shanghai`. | | `RUN_ARIA2` | | Whether to run ARIA2 concurrently, default is `true` if aria2 is pre-installed, otherwise it is `false`. | @@ -105,8 +203,8 @@ docker compose up -d ::: zh-CN | 名称 | 默认值 | 说明 | | :---------- | :----- | -------------------------------------------------------------------------- | -| `PUID` | `0` | 运行身份 UID | -| `PGID` | `0` | 运行身份 GID | +| `PUID` | `0` | 运行身份 UID,在 v4.1.0 以后的版本中废弃 | +| `PGID` | `0` | 运行身份 GID,在 v4.1.0 以后的版本中废弃 | | `UMASK` | `022` | https://en.wikipedia.org/wiki/Umask | | `TZ` | `UTC` | 默认为 UTC 时区,如果你想指定时区,则可以设置此变量,例如:`Asia/Shanghai` | | `RUN_ARIA2` | | 是否同时运行 ARIA2,当镜像含有 aria2 环境时默认为 `true`,否则为 `false` | @@ -299,9 +397,6 @@ docker rm ID # Pull the latest image of OpenList docker pull openlistteam/openlist:latest - -# Enter the installation command -docker run -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="openlist" openlistteam/openlist:latest ``` ::: @@ -320,14 +415,49 @@ docker rm ID # 拉取 OpenList 的最新镜像 docker pull openlistteam/openlist:latest +``` -# 输入安装命令 -docker run -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="openlist" openlistteam/openlist:latest +::: + +#### 升级到 v4.1.0 以后版本 (不包括v4.1.0) { lang="zh-CN" } + +#### Upgrade to version v4.1.0 and later (excluding v4.1.0) { lang="en" } + +::: en +::: tip +If you want to run and manage OpenList and its configuration directory using the default OpenList user (1001) inside the container, please use the following command: +::: +::: zh-CN +::: tip +如果您希望使用 1001,即容器内置的默认 `openlist` 用户运行和管理 OpenList 及其配置目录,请使用以下命令: +::: + +```bash +chown -R 1001:1001 /etc/openlist +docker run -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e UMASK=022 --name="openlist" openlistteam/openlist:latest ``` +::: en +::: tip +If you are using the current user to run and manage OpenList and its configuration directory, please use the following command: +::: +::: zh-CN +::: tip +如果您希望使用当前用户运行和管理 OpenList 及其配置目录,请使用以下命令: ::: -![docker](/img/faq/updocker.png) +```bash +sudo chown -R $(id -u):$(id -g) /etc/openlist +docker run --user $(id -u):$(id -g) -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e UMASK=022 --name="openlist" openlistteam/openlist:latest +``` + +#### 升级到 v4.1.0 以前的版本(包括 v4.1.0) { lang="zh-CN" } + +#### Upgrade to version v4.1.0 and earlier (including v4.1.0) { lang="en" } + +```bash +docker run -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="openlist" openlistteam/openlist:latest +``` ### Docker Compose @@ -367,6 +497,121 @@ Write the content below. Then save and exit. 写入以下内容,然后保存并退出: ::: +#### For version after v4.1.0 { lang="en" } + +#### v4.1.0 以后版本 { lang="zh-CN" } + +```yaml +# docker-compose.yml +services: + # OpenList | OpenList Core Service + openlist: + image: 'openlistteam/openlist:latest' + container_name: openlist + volumes: + - '${OPLISTDX_DATA}/openlist:/opt/openlist/data' + - '${OPLISTDX_TEMP}/aria2:/opt/openlist/data/temp/aria2' + - '${OPLISTDX_TEMP}/qBittorrent:/opt/openlist/data/temp/qBittorrent' + - '${OPLISTDX_TEMP}/Transmission:/opt/openlist/data/temp/Transmission' + user: '${OPLISTDX_PUID}:${OPLISTDX_PGID}' # If you are using v4.1.0 later, must uncomment this line and set the correct user ID and group ID. + ports: + - '5244:5244' + environment: + # - PUID=${OPLISTDX_PUID} # Deprecated in v4.1.0 later versions + # - PGID=${OPLISTDX_PGID} # Deprecated in v4.1.0 later versions + - TZ=${OPLISTDX_TZ} + - UMASK=022 + restart: unless-stopped + + # # Aria2 下载器及webui | Aria2 Downloader & WebUI + # aria2-pro: + # image: p3terx/aria2-pro + # container_name: aria2-pro + # restart: unless-stopped + # ports: + # - '6800:6800' + # - '6888:6888' + # - '6888:6888/udp' + # volumes: + # - '${OPLISTDX_DATA}/aria2-pro:/config' + # - '${OPLISTDX_DOWNLOADS}/aria2:/downloads' + # - '${OPLISTDX_TEMP}/aria2:/opt/openlist/data/temp/aria2' + # environment: + # - 'PUID=${OPLISTDX_PUID}' + # - 'PGID=${OPLISTDX_PGID}' + # - 'TZ=${OPLISTDX_TZ}' + # - 'UMASK_SET=022' + # - 'RPC_SECRET=${OPLISTDX_ARIA2TOKEN}' + # - 'RPC_PORT=6800' + # - 'LISTEN_PORT=6888' + # ariang: + # container_name: ariang + # image: p3terx/ariang + # command: --port 6880 + # ports: + # - 6880:6880 + # restart: unless-stopped + # environment: + # - 'PUID=${OPLISTDX_PUID}' + # - 'PGID=${OPLISTDX_PGID}' + # - 'TZ=${OPLISTDX_TZ}' + # logging: + # driver: json-file + # options: + # max-size: 1m + # depends_on: + # - aria2-pro + + # # qBittorrent 下载器 | qBittorrent Downloader + # qbittorrent: + # image: lscr.io/linuxserver/qbittorrent:latest + # container_name: qbittorrent + # environment: + # - PUID=${OPLISTDX_PUID} + # - PGID=${OPLISTDX_PGID} + # - TZ=${OPLISTDX_TZ} + # - WEBUI_PORT=8080 + # - TORRENTING_PORT=6881 + # volumes: + # - '${OPLISTDX_DATA}/qbittorrent:/config' + # - '${OPLISTDX_DOWNLOADS}/qbittorrent:/downloads' + # - '${OPLISTDX_TEMP}/qBittorrent:/opt/openlist/data/temp/qBittorrent' + # ports: + # - 8080:8080 + # - 6881:6881 + # - 6881:6881/udp + # restart: unless-stopped + + # # Transmission 下载器 | Transmission Downloader + # transmission: + # image: lscr.io/linuxserver/transmission:latest + # container_name: transmission + # environment: + # - PUID=${OPLISTDX_PUID} + # - PGID=${OPLISTDX_PGID} + # - TZ=${OPLISTDX_TZ} + # - TRANSMISSION_WEB_HOME=${OPLISTDX_TRANSMISSION_WEB_HOME} #optional + # - USER=${OPLISTDX_TRANSMISSION_USER} #optional + # - PASS=${OPLISTDX_TRANSMISSION_PASS} #optional + # - WHITELIST=${OPLISTDX_TRANSMISSION_WHITELIST} #optional + # - PEERPORT=${OPLISTDX_TRANSMISSION_PEERPORT} #optional + # - HOST_WHITELIST=${OPLISTDX_TRANSMISSION_HOST_WHITELIST} #optional + # volumes: + # - '${OPLISTDX_DATA}/transmission:/config' + # - '${OPLISTDX_DOWNLOADS}/transmission:/downloads' + # - '${OPLISTDX_TRANSMISSIONWATCH}:/watch' + # - '${OPLISTDX_TEMP}/Transmission:/opt/openlist/data/temp/Transmission' + # ports: + # - 9091:9091 + # - 51413:51413 + # - 51413:51413/udp + # restart: unless-stopped +``` + +#### For version v4.1.0 and earlier { lang="en" } + +#### v4.1.0 及以前版本 { lang="zh-CN" } + ```yaml # docker-compose.yml services: @@ -379,11 +624,12 @@ services: - '${OPLISTDX_TEMP}/aria2:/opt/openlist/data/temp/aria2' - '${OPLISTDX_TEMP}/qBittorrent:/opt/openlist/data/temp/qBittorrent' - '${OPLISTDX_TEMP}/Transmission:/opt/openlist/data/temp/Transmission' + # user: "${OPLISTDX_PUID}:${OPLISTDX_PGID}" # If you are using v4.1.0 later, must uncomment this line and set the correct user ID and group ID. ports: - '5244:5244' environment: - - PUID=${OPLISTDX_PUID} - - PGID=${OPLISTDX_PGID} + - PUID=${OPLISTDX_PUID} # Deprecated in v4.1.0 later versions + - PGID=${OPLISTDX_PGID} # Deprecated in v4.1.0 later versions - TZ=${OPLISTDX_TZ} - UMASK=022 restart: unless-stopped diff --git a/public/img/faq/updocker.png b/public/img/faq/updocker.png deleted file mode 100644 index 2223e0f4f..000000000 Binary files a/public/img/faq/updocker.png and /dev/null differ