说起来，

说明

Alist 是一个轻量级的存储管理项目。源码位于 https://github.com/AlistGo/alist。它支持通过挂载配置文件来自定义行为，也可以实现数据持久化。说起来，为避免手动维护依赖与环境。建议使用最新的 Docker 镜像部署。

准备文件

克隆或下载官方提供的快速部署仓库：

git clone https://gitcode.com/zhudev2026/alist-deploy.git
cd alist-deploy

快速部署

如果你只想在全新机器上“即开即用”。不需要任何自定义，只需执行：

docker compose up -d

Docker 会自动拉取最新的 alist 镜像并在后台启动容器。

常见痛点 & 方法

• 找不到默认密码首次启动后容器日志会输出随机生成的管理员密码。话说回来，
• 端口冲突默认映射 :80和 :443如已被占用请在 compose.yaml 中自行修改。
• 数据不持久化未挂载卷时容器重启会导致数据丢失，请务必使用下面的自定义配置章节来绑定本地目录。
• 自定义 config.json 找不到位置将本地的 config.json 挂载到容器的 /opt/alist/data/config.json 即可生效。
• 容器无法启动或报错 “connection refused” : 检查宿主机是否已占用对应端口，或确认网络策略未阻断。

查询容器状态 & 获取密码

查看容器运行状态：

docker compose ps -a
# 示例输出
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
alist swr.cn-north-.myhuaweicloud.com/ddn-k8s/ghcr.io/alistgo/alist:v3.0 "/entrypoint.sh" alist 5 seconds ago Up 5 seconds 0.0.0.0:80->80/tcp。:::80->80/tcp

获取自动生成的管理员密码：

docker logs alist | grep "initial password"
# 示例输出
INFO Successfully created admin user and initial password is: wrwiNx53

访问 Alist Web UI

打开浏览器访问服务器 IP即可进入登录页：

• 默认账户：admin
• 密码：上一步日志中打印的随机密码，例如 wrwiNx53
• 首次登录建议：立即前往「管理 → 配置 → 存储」页面添加你实际使用的云盘或本地挂载，否则只能看到空白列表。

自定义配置

1️⃣ 修改 compose.yaml

services:
再看alist，# 官方镜像地址，请务必使用对应版本号，如 v3.6.2
从image来看，swr.cn-north-.myhuaweicloud.com/ddn-k8s/ghcr.io/alistgo/alist:v3.6.2
container_name: alist
# ==== 数据持久化 ====
volumes:
- 'alist_data:/opt/alist/data' # 持久化整个 data 目录
- ./config.json:/opt/alist/data/config.json # 挂载自定义配置
# ==== 端口映射 ====
再看ports，- '8080:80' # 将宿主机 8080 映射到容器内部 HTTP端口
# ==== 环境变量 ====
environment:
- PUID=1000 # 主机使用者 ID，建议与宿主机实际使用者保持一致
- PGID=1000 # 主机使用者组 ID
- UMASK=022 # 文件权限掩码
restart: unless-stopped
networks:
- alist-net
volumes:
alist_data:
至于name。alist_data # 本地卷名称，可自行修改
networks:
alist-net:
再看name，alist-net
说到driver，bridge

2️⃣ 编写 config.json

If you need custom storage back‑ends or advanced features,create a config.json` in project root and mount it as shown above.

{
"force": false,"site_url": "","jwt_secret": "YRaOORpTQDoWMQn5","database": {
"type"这方面，"sqlite3","db_file": "data/data.db"
},"scheme": {
"address": ".","http_port": 80,"https_port": 443,"force_https": false
},"log": {
"enable": true,"name": "data/log/log.log","max_size": 10,"max_backups": 5,"max_age": 30,"compress": false
},//…，更多细节请参考官方文档 https://alistgo.com/config/configuration.html
}

3️⃣ 重启以加载新配置

docker compose down # 停止旧实例
docker compose up -d # 启动新实例。读取挂载的 config.json

故障排查小技巧 🎯

• : 使用 # docker ps | grep :80$  查看冲突容器，或直接修改 .yaml> ports:.
• : 确认镜像版本>= v3.4；说起来，旧版会在首次启动后写入 /opt/alist/data/admin.password.txt.
• : 检查对应服务是否已开放网络、是否在同一 Docker network 中、还有 API 密钥是否正确。
• : 查看完整日志 # docker logs alist --tail=100 --follow ;常见原因是卷权限错误，可尝试在宿主机执行

  chown -R $:$ ./alist_data ./config.json
  chmod -R 755 ./alist_data
  

结束语 & 推荐实践 ✅

- 始终使用官方提供的带版本号镜像。避免 “latest” 带来的不可预期升级。- 将 /opt/alist/data/​*/​**​*​*​**​*​*​**​**​​ ​**​​ ​**​​ **​​**​​ **​​ **​​ **​​ **​​ **​​​ 为独立卷，以便随时备份 / 恢复。- 定期检查日志文件大小并开启日志轮转，以免磁盘被填满。- 若需要 HTTPS，请在宿主机前置 Nginx / Caddy 或直接在 Alist 中配置证书方法。

祝您部署顺利 🚀 如有其他疑问，请随时反馈！