常见错误及解决方法

使用了一段时间后，数据库无法启动或连接 点击这里

容器启动后无法访问

请检查容器是否正确映射了端口、目录，以及访问的IP、端口号是否正确；

排除了IP、端口、目录映射的原因之后，通常是内置的PostgreSQL数据库无法初始化或者启动导致的；

因为PostgreSQL数据库的数据文件都存在容器内的/config/pgsql 目录中，而这个目录的拥有者必须为容器内的postgres用户且目录权限为drwx------(即700)，否则数据库无法正常运行；

已知的问题：

1、通过SMB或者NFS挂载的远程目录，无法作为/config/pgsql目录

2、如果硬盘的文件系统为exFAT格式，无法作为/config/pgsql目录

3、/config/pgsql目录不要使用ACL权限

4、/config目录映射的不是默认的docker目录
请检查/config目录Everyone是否有读取权限检查方法点击这里

极空间创建容器后，数据库提示权限问题

在添加/config 的目录映射时，需要添加真实路径的方式添加真实路径

UNRAID系统请检查 Settings (设置) => ShareSettings (全局共享设置) 中Tunable (support Hard Links) (可调式支持硬链接) 的值是否为 Yes (是)

因为PostgreSQL会针对/config/pgsql内的文件进行硬链接操作

提示：如果宿主机的硬盘较小，担心缩略图目录(/config/cache)占用的空间过大，可以额外配置缩略图的位置

第一次安装时，数据库无法初始化：

以下3种解决方法都可以解决目录权限的问题，选择一种您熟悉的方式即可：

1.使用volume作为数据库目录（推荐👍）
2.指定PUID、PGID运行
3.在宿主机中修改目录权限
4.单独安装数据库，然后连接外部数据库

一、在日志中找到有用的错误信息

查看docker容器的日志，看本次启动是否有以下情况：

1、如何是第一次安装，请查看容器日志的最开始部分。

===== initDbPath =====
更多日志...
可能包含错误信息

2、如果是在使用了一段时间后无法访问，请先重启容器，然后查看本次启动日志的最开始部分。部分情况下，重启容器后即可正常访问服务器；这类情况通常是/config/pgsql目录的权限在外部被修改导致的。

历史日志...
2022-11-01T16:07:01: PM2 log: pid=72 msg=process killed
2022-11-01T16:07:01: PM2 log: PM2 successfully stopped
waiting for server to shut down.... done
server stopped
Process finished
===== updateDbPath ===== 
waiting for server to start....
更多日志...

上面日志从 “===== updateDbPath ===== ”开始为本次启动的日志；
错误信息在这后面会出现。

二、错误类型：

看日志开始部分是否有以下错误：

sh /usr/app/initDb.sh chmod: changing permissions of '/config/pgsql': Operation not permitted;
init db error: could not access directory "/config/pgsql/data": Permission denied;

等和/config/pgsql目录权限有关的错误；

解决方法：

以下3种解决方法都可以解决目录权限的问题，选择一种您熟悉的方式即可：

1.使用volume作为数据库目录（推荐👍）
2.指定PUID、PGID运行
3.在宿主机中修改目录权限
4.单独安装数据库，然后连接外部数据库

3、目录权限解决方法：

1. 使用Docker Volume作为数据库目录（推荐👍）

如果系统支持使用docker compose创建容器，可以针对数据库目录 /config/pgsql ，单独使用数据卷Volume；

这样可以避免因为目录权限问题导致错误；

需要在 volumes: 中添加一行 - mt_photos_pg:/config/pgsql

以及结尾的

volumes:
  mt_photos_pg:

完整的yaml模板：

version: "3"

services:
  mtphotos:
    image: registry.cn-hangzhou.aliyuncs.com/mtphotos/mt-photos:latest
    container_name: mt-photos
    restart: always
    ports:
      - 8063:8063
    volumes:
      - /share/Container/mt_photos:/config
      - mt_photos_pg:/config/pgsql
      - /share/Public/mt_photos_upload:/upload
    environment:
      - TZ=Asia/Shanghai
      - PUID=1000
      - PGID=100
volumes:
  mt_photos_pg:

Docker Volume能让容器从宿主主机中读取文件或持久化数据到宿主主机内，让容器与容器产生的数据分离开来。你可以简单地把它理解为linux服务器上的挂载点。一个容器可以挂载多个不同的目录。Volume的生命周期是独立于容器的生命周期之外的，即使容器删除了，volume也会被保留下来，Docker也不会因为这个volume没有被容器使用而回收。在容器中，添加或修改这个文件夹里的文件也不会影响容器的联合文件系统。

注：每创建一个volume，docker会在/var/lib/docker/volumes/下创建一个子目录，默认情况下目录名是一串UUID。如果指定了名称，则目录名是volume名称（例如上面的mt_photos_pg）。volume里的数据都存储在这个子目录的_data目录下。

修改时，请遵循 yaml语法三大规则

方法2：指定PUID、PGID运行

举例：假设MT Photos容器的目录映射为：

宿主机(/mnt/user/appdata/MtPhotos/config) => 容器(/config)
宿主机(/mnt/user/photos/upload) => 容器(/upload)

步骤：

确认容器配置中/config/目录是否有读写权限；
将宿主机中的/mnt/user/appdata/MtPhotos/config(即例子中映射容器的/config/)目录的拥有者改为系统中某个非root用户
获取这个用户的uid、gid，在系统的终端中执行 id xxx 即可获取用户的uid、gid；比如下图中用户media的uid为1002，gid为100
为容器添加环境变量：PUID、PGID（相关说明见环境变量）
启动容器

注意：PUID、PGID 不能为0

方法3：在宿主机中修改目录权限

可按照以下步骤检查 /config/pgsql目录的权限：

容器的终端执行 ls -l /config，确定/config/pgsql目录权限是否为 drwx------(即700) 且用户、用户组为postgres，如果权限和下面截图的不一致，执行下面的步骤。
容器的终端执行 id postgres ，获取容器内postgres的uid、gid
宿主机的终端执行cd /xxx/config, 跳转到config目录中(即例子中映射容器的/config/)
宿主机的终端执行sudo chmod 700 -R pgsql , sudo chown 103:105 -R pgsql 提示：103和105为第二步执行后，容器内postgres的uid和gid
等待第4步命令执行完成，重启容器

/config目录映射的不是默认的docker目录

如遇到目录权限问题，可以检查/xxx/config/(即例子中映射容器的/config/)目录的权限；

1、Owner是否有完全控制权限
2、Everyone是否有读取权限

如果没有，请按以下步骤添加；添加完成后，重启MT Photos容器；

如果无法添加权限，建议 /config 映射默认的 docker目录

如果宿主机的硬盘较小，担心缩略图目录(/config/cache)占用的空间过大，可以额外配置缩略图的存储位置

添加方法如下：

极空间在添加/config 的目录映射时，需要添加真实路径

添加真实路径：

方法4：连接外部数据库

如果您对遇上2种方法不熟悉，可以单独安装PostgreSQL数据库，然后连接外部数据库查看使用教程

使用了一段时间后，数据库无法启动或连接

看日志开始部分是否有以下错误：

ERROR [TypeOrmModule] Unable to connect to the database.
pg_ctl:could not start server

那么需要查看数据库日志/config/pgsql/serverlog最新的日志；

寻找FATAL、PANIC开头的日志；

根据日志内容，可能存在以下几种情况：

2.1、数据库目录权限错误

错误信息：

FATAL: data directoy "/config/pgsql/data" has invalid permissions

解决方法：

在宿主机中修改目录权限

2.2、数据库目录文件丢失

错误信息：

FATAL： could not open directory "pg_notify"：No such file or directiry

等 No such file or directiry的错误的

解决方法：

请对照以下目录列表，检查是否有缺少的文件夹，新建缺少的文件夹，然后重启容器即可；

# /config/pgsql/data下的文件夹

├── base
│   ├── 1
│   ├── 13704
│   └── 13705
├── global
├── pg_commit_ts
├── pg_dynshmem
├── pg_logical
│   ├── mappings
│   └── snapshots
├── pg_multixact
│   ├── members
│   └── offsets
├── pg_notify
├── pg_replslot
├── pg_serial
├── pg_snapshots
├── pg_stat
├── pg_stat_tmp
├── pg_subtrans
├── pg_tblspc
├── pg_twophase
├── pg_wal
│   └── archive_status
└── pg_xact

2.3、数据库找不到有效的检查点记录

错误信息：

PANIC:  could not locate a valid checkpoint record

或者 pg_wal 文件下的文件丢失

FATAL: could not open file "pg_wal/000000010000000000000006": No such file or directory

解决方法：

启动容器；
进入容器的终端内执行以下命令
su postgres -c '/usr/lib/postgresql/14/bin/pg_resetwal -f /config/pgsql/data'
等待命令执行完成后重启容器；

常见错误及解决方法

容器启动后无法访问

第一次安装时，数据库无法初始化：

一、在日志中找到有用的错误信息

二、错误类型：

解决方法：

3、目录权限解决方法：

1. 使用Docker Volume作为数据库目录（推荐👍）

方法2：指定PUID、PGID运行

方法3：在宿主机中修改目录权限

/config目录映射的不是 默认的docker目录

极空间在添加/config 的目录映射时，需要 添加真实路径

方法4：连接外部数据库

使用了一段时间后，数据库无法启动或连接

2.1、数据库目录权限错误

解决方法：

2.2、数据库目录文件丢失

2.3、数据库找不到有效的检查点记录

/config目录映射的不是默认的docker目录

极空间在添加/config 的目录映射时，需要添加真实路径