LinkStack 4.8.8 Docker Compose 部署指南

用官方镜像 linkstackorg/linkstack:v4.8.8 通过 Docker Compose 部署 LinkStack（MariaDB 11.4 系统库），完整走通六步安装向导并验证建表、登录与页面访问，含环境变量注入、/htdocs 整体持久化与 6 则实测排障。

LinkStackLinkStack面板书签管理PHP 应用Docker Compose2026/11/03

LinkStack 4.8.8 Docker Compose 部署指南

目标：用官方镜像 linkstackorg/linkstack:v4.8.8 通过 Docker Compose 部署 LinkStack（PHP/Laravel 自托管链接管理与 link-in-bio 面板），搭配 MariaDB 11.4 作为系统数据库，完整走通六步安装向导（语言→依赖检查→数据库类型→MySQL 连接→管理员账号→站点选项），并完成建表、登录与页面访问验证。已在 Ubuntu 22.04（x86_64）服务器、LinkStack 4.8.8 上全量实测通过。

一、环境信息

本文所有命令与输出均在以下环境实测采集：

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • Docker：29.9.2（含 Docker Compose v5.6.1 插件，docker --version / docker compose version 实测）
  • LinkStack：v4.8.8（官方镜像 linkstackorg/linkstack:v4.8.8，Docker Hub 更新于 2026-10-22，本地解压后 441MB）
  • 应用内技术栈：Alpine Linux + Apache 2.4.69（mod_ssl/OpenSSL 3.5.9）+ PHP 8.3.36 + Laravel Framework 9.52.22（php83 artisan --version 实测）
  • 系统数据库：MariaDB 11.4（官方镜像 mariadb:11.4，客户端版本 11.4.13 实测）
  • 访问端口：宿主机 8132 → 应用 80（HTTP）、8134 → 443（HTTPS，镜像自带自签名证书）
  • 部署目录：/opt/linkstack-stack/（本文示例路径，读者可自定）
  • 管理账号：邮箱 root@quzuo.net / 口令 q1w2e3r4，主页句柄 @root
  • 实测日期：2026-11-02

💡 技术拓展：LinkStack 的系统数据库不止一种选择。安装向导可选的类型对比——

类型特点适用场景
SQLite官方向导默认推荐，零外部依赖，单文件落 /htdocs/database/个人单页、试用
MySQL独立服务，并发写入与备份工具链成熟多用户注册的生产实例（本文采用）
MariaDB与 MySQL 走同一 mysql 驱动（向导无独立 MariaDB 选项）已有 MariaDB 运维体系（本文实际部署）
PostgreSQL镜像已带 pdo_pgsql 扩展，但向导未暴露选项，需装后改 .env+手工迁移已有 PG 栈（非官方推荐路径）

本文实际采用 MariaDB（以 MySQL 类型接入）：LinkStack 支持访客统计、多用户注册等并发写场景，外部数据库便于备份与扩容；个人试用选 SQLite 更省事。

⚠️ 网络说明：本服务器直连 hub.docker.com API 不可用（curl 超时），查询镜像 tag 已改用代理 http://192.168.1.72:7897（实测可用）；docker pull 走守护进程配置的代理 192.168.1.62:7897 正常拉取。国内环境如无代理，可先配置 registry 镜像加速再拉取。

二、镜像选型说明

官方镜像发布于 Docker Hub linkstackorg/linkstack（备选 GitHub 镜像仓库 ghcr.io/linkstackorg/linkstack），实测 tag 列表（hub.docker.com API，2026-11-02）：

镜像 tag说明建议
v4.8.8当前最新稳定版，与 GitHub Release v4.8.8（2026-10-22）对应✅ 生产推荐，锁定版本
latest跟随最新发布（当前即 4.8.8，2026-10-22 更新）测试可用，生产不建议（升级不可控）
v4.8.7 / v4.8.6 等历史版本回滚用
amd64 / arm32v6 / arm32v7 / arm64v8单架构 tag（2023 年停更，勿用）新部署一律用版本号 tag
laravel12 / beta下一代 Laravel 12 预发布线生产禁用
unraid / V4特殊用途/历史 tag勿用

两种部署形态对比（本文选方案 B）：

  • 方案 A：源码直装——下载 GitHub Release 的 linkstack.zip 解到 Web 根目录，"拖放即装"。适合已有 LAMP 主机/虚拟主机用户，但依赖自行配 PHP 8.0+ 与扩展；
  • 方案 B：官方预构建镜像——linkstackorg/linkstack:v4.8.8 自带 Alpine + Apache + PHP 8.3 全栈，docker compose up -d 即起，版本与 GitHub Release 一一对应。

关键差异：方案 B 部署快、环境一致、升级换 tag 即可；只有虚拟主机等无法用容器的场景才走方案 A。

三、前置条件

  1. Docker 与 Compose 插件：宿主机安装 Docker 24+ 与 docker compose（docker compose version 可确认，本文实测 v5.6.1）；
  2. 端口空闲：确认 8132/8134 未被占用：ss -ltn | grep -E ':8132|:8134' 无输出即可；
  3. 网络可达：能拉取 Docker Hub 镜像（见第一章网络说明）；
  4. 数据库规划：一个空的 MariaDB/MySQL 实例与账号（本文用 Compose 一并编排），LinkStack 建表时会自动执行 12 条迁移，库必须为空；
  5. 资源：应用 441MB + MariaDB 约 500MB 镜像，内存建议 ≥1GB，磁盘预留 2GB（内置更新器每次升级会留 zip 备份，见第五章）。

四、部署步骤

4.1 建立部署目录与编排文件

mkdir -p /opt/linkstack-stack && cd /opt/linkstack-stack

/opt/linkstack-stack/docker-compose.yml（完整内容，逐项说明见第六、七章）：

name: linkstack-4-8-8-stack

services:
  db:
    image: mariadb:11.4
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: q1w2e3r4
      MARIADB_DATABASE: linkstack
      MARIADB_USER: linkstack
      MARIADB_PASSWORD: q1w2e3r4
    volumes:
      - linkstack-db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 5s
      timeout: 5s
      retries: 10

  linkstack:
    image: linkstackorg/linkstack:v4.8.8
    hostname: linkstack
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      TZ: Asia/Shanghai
      SERVER_ADMIN: admin@quzuo.net
      HTTP_SERVER_NAME: localhost
      HTTPS_SERVER_NAME: localhost
      LOG_LEVEL: info
      PHP_MEMORY_LIMIT: 256M
      UPLOAD_MAX_FILESIZE: 16M
    volumes:
      - linkstack-data:/htdocs
    ports:
      - "8132:80"
      - "8134:443"

volumes:
  linkstack-db:
    driver: local
  linkstack-data:
    driver: local

要点解读：

  • name: linkstack-4-8-8-stack 显式声明项目名，避免与其他在跑的编排互相干扰；版本号中的点会被 Compose 规范化为连字符（实测项目名即此形式）；
  • db 服务用官方镜像标准变量初始化：root 口令 q1w2e3r4、自动建库 linkstack、建用户 linkstack/q1w2e3r4；
  • healthcheck + depends_on.condition: service_healthy 保证 MariaDB 完成初始化后 LinkStack 才启动，避免向导连库失败；
  • linkstack 服务把整个 /htdocs 目录挂到命名卷（官方推荐做法，原因见第五章）；
  • 双端口映射：80/443 都在镜像内监听（自签名证书），HTTP 走 8132，HTTPS 走 8134。

4.2 拉取镜像

cd /opt/linkstack-stack && docker compose pull

实测输出（节选，尾部）：

 123724ef3154 Pull complete 0B
 3651b1463476 Pull complete 0B
 fd77be06c448 Pull complete 0B
 Image linkstackorg/linkstack:v4.8.8 Pulled

确认镜像落地：

docker images --format '{{.Repository}}:{{.Tag}} {{.Size}}' | grep linkstack

实测输出：

linkstackorg/linkstack:v4.8.8 441MB

4.3 启动整套服务

cd /opt/linkstack-stack && docker compose up -d

实测输出（节选）：

 Volume "linkstack-4-8-8-stack_linkstack-db"  Created
 Volume "linkstack-4-8-8-stack_linkstack-data"  Created
 Network linkstack-4-8-8-stack_default  Created
 Container linkstack-4-8-8-stack-db-1  Started
 Container linkstack-4-8-8-stack-db-1  Healthy
 Container linkstack-4-8-8-stack-linkstack-1  Started

db 先达到 Healthy、linkstack 随后启动，说明依赖门控生效。确认状态：

docker compose ps

实测输出：

NAME                                IMAGE                           COMMAND                  SERVICE     CREATED          STATUS                    PORTS
linkstack-4-8-8-stack-db-1          mariadb:11.4                    "docker-entrypoint.s…"   db          26 seconds ago   Up 23 seconds (healthy)   3306/tcp
linkstack-4-8-8-stack-linkstack-1   linkstackorg/linkstack:v4.8.8   "docker-entrypoint.sh"   linkstack   25 seconds ago   Up 8 seconds              0.0.0.0:8132->80/tcp, [::]:8132->80/tcp, 0.0.0.0:8134->443/tcp, [::]:8134->443/tcp

查看应用启动日志，确认版本横幅与 PHP 参数注入：

docker compose logs linkstack | head -14

实测输出（节选）：

linkstack-1  | + ------------------------------------------------------------------ +
linkstack-1  | |                      LINKSTACK v4.8.8                      |
linkstack-1  | + ------------------------------------------------------------------ +
linkstack-1  | | Updating Configuration: Apache Base (/etc/apache2/httpd.conf)      |
linkstack-1  | | Updating Configuration: Apache SSL  (/etc/apache2/conf.d/ssl.conf) |
linkstack-1  | | Updating Configuration: PHP         (/etc/php83/40-custom.ini)     |
linkstack-1  | | Setting PHP Configuration:                                         |
linkstack-1  | | upload_max_filesize = 16M                       |
linkstack-1  | | memory_limit = 256M                                 |
linkstack-1  | | date.timezone = Asia/Shanghai                                              |
linkstack-1  | | Updating Configuration: Complete                                   |
linkstack-1  | | ------------------------------------------------------------------ |
linkstack-1  | | Running Apache                                                     |

4.4 验证 HTTP/HTTPS 可达

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8132/
curl -sI http://127.0.0.1:8132/ | head -3
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8134/

实测输出：

200
HTTP/1.1 200 OK
Date: Mon, 02 Nov 2026 17:06:41 GMT
Server: Apache/2.4.69 (Unix)
200

Server: Apache/2.4.69、X-Powered-By: PHP/8.3.36（响应头实测）确认全栈就绪；此时首页已是安装向导（标题 LinkStack setup）。

4.5 完成安装向导（六步）

浏览器访问 http://<服务器IP>:8132/，向导按 ?步骤号 推进，各步提交后服务端 302 跳转到下一步。以下每步给出界面操作与实测的请求/响应证据（实测通过 HTTP 客户端逐步提交，与浏览器点按等价）。

第 1 步：选择语言。 页面 Setup LinkStack，下拉框选 English（也可选 简体中文），提交后写入 .env 的 LOCALE 并跳转：

POST /editConfigInstaller  (type=homeurl, entry=LOCALE, value=en)
HTTP/1.1 302 Found
Location: http://127.0.0.1:8132/dashboard

第 2 步：依赖检查（?2）。 页面列出 PHP 必需扩展与数据库支持，全绿后点 Next 进入 ?3。实测页面内容：

Dependency check
Required PHP modules: BCMath: Ctype: cURL: DOM: Fileinfo: JSON: iconv:
Mbstring: OpenSSL: PCRE: PDO: Tokenizer: XML:
Depending on your database type: SQLite: MySQL:

第 3 步：选择数据库类型（?3）。 Database type 下拉框只有 SQLite / MySQL 两项（MariaDB 按 MySQL 协议接入，见第一章拓展）。选 MySQL 提交：

POST /db  (database=MySQL)
HTTP/1.1 302 Found
Location: http://127.0.0.1:8132?mysql

第 4 步：填写 MySQL 连接参数（?mysql）。 五个输入框对应数据库五要素，填编排中的服务名与账号：

Database host: db
Database port: 3306
Database name: linkstack
Database username: linkstack
Database password: q1w2e3r4

实测提交与自动连通性验证：

POST /mysql
HTTP/1.1 302 Found
Location: http://127.0.0.1:8132/mysql-test
GET /mysql-test  → 页面自动跳转：Redirecting to http://127.0.0.1:8132?4

/mysql-test 会用刚填的参数真实连库测试，通过后自动进入第 5 步；若连接失败则停在该页报错（排障见第十一章 Q5）。

第 5 步：创建管理员账号（?4）。 四个字段：

Admin email: root@quzuo.net
Admin password: q1w2e3r4
Handle: root          （主页地址即 /@root）
Name: root

实测提交：

POST /create-admin
HTTP/1.1 302 Found
Location: http://127.0.0.1:8132?5

第 6 步：站点选项（?5），点 Finish setup 收尾。 实测提交：

POST /options  (register=Yes, verify=No, page=No, app=LinkStack)
HTTP/1.1 302 Found
Location: http://127.0.0.1:8132/dashboard

四项含义：Enable registration（是否允许访客注册，Yes）、Enable email verification（注册是否需邮箱验证，No）、Set your page as Home Page（是否把管理员主页设为首页，No）、App Name（站点显示名，LinkStack）。

4.6 验证数据库建表

向导完成即自动执行全部迁移。连到 MariaDB 查库：

docker compose exec db mariadb -ulinkstack -pq1w2e3r4 linkstack -e "SHOW TABLES;"

实测输出：

Tables_in_linkstack
buttons
failed_jobs
link_types
links
migrations
pages
password_resets
social_accounts
users
visits

10 张表：users（用户）、links/buttons/link_types（链接与按钮）、pages（自定义页）、visits（访客统计）、social_accounts（社交登录）、migrations/failed_jobs/password_resets（框架表）。

4.7 验证登录与页面

curl -s -c login.txt http://127.0.0.1:8132/login -o /dev/null
# 页面含 CSRF 字段 _token，携带邮箱/口令提交登录
curl -s -b login.txt -c login.txt -X POST http://127.0.0.1:8132/login \
  -d "email=root@quzuo.net" -d "password=q1w2e3r4" -d "_token=<页面取回的token>" \
  -o /dev/null -D - | grep -iE '^HTTP|^location'
curl -s -b login.txt -o /dev/null -w 'dashboard=%{http_code}\n' http://127.0.0.1:8132/dashboard
curl -s -o /dev/null -w 'userpage=%{http_code}\n' http://127.0.0.1:8132/@root

实测输出：

HTTP/1.1 302 Found
Location: http://127.0.0.1:8132/dashboard
dashboard=200
userpage=200

用 root@quzuo.net / q1w2e3r4 在浏览器登录管理后台（/dashboard）同样返回 200；访客页 http://<服务器IP>:8132/@root 已可访问。至此部署完成。

⚠️ 注意：Finish setup 后服务端会结束安装会话，直接访问 /dashboard 会 302 到 /login（实测回显 Redirecting to http://127.0.0.1:8132/login），属正常行为，重新登录即可。

五、数据持久化说明

官方明确要求把应用根目录 /htdocs 整体持久化——LinkStack 的代码、.env、主题、头像、存储与升级备份全在其中：

docker volume ls | grep linkstack

实测输出：

local     linkstack-4-8-8-stack_linkstack-data
local     linkstack-4-8-8-stack_linkstack-db
卷名（实际生成）挂载点存放内容
linkstack-4-8-8-stack_linkstack-data/htdocs应用全目录：.env、config/（含 advanced-config.php）、database/（SQLite 形态的库文件）、themes/、storage/、backups/（升级备份）、assets/（头像等）
linkstack-4-8-8-stack_linkstack-db/var/lib/mysqlMariaDB 数据目录（本文 MySQL 形态下所有业务表在此）

/htdocs 内与持久化直接相关的关键路径（官方文档列举的选择性保存清单 + 本文实测）：

/htdocs/.env
/htdocs/config/advanced-config.php
/htdocs/assets/linkstack/images/avatar.png
/htdocs/themes（目录）
/htdocs/assets/img（目录）
/htdocs/storage（会话、缓存、日志、备份）
/htdocs/backups（内置更新器的升级备份 zip）

数据库备份（实测）：

docker compose exec -T db mariadb-dump linkstack > linkstack-db-$(date +%F).sql

应用+数据库整包备份可用内置命令 php83 artisan backup:run（实测产物 21.42MB zip、含 10722 个文件，落在 /htdocs/backups/；该命令在 MySQL 形态需先修两处配置，详见第十一章 Q3 与《LinkStack 4.8.8 常用 CLI 命令与工具详解》）。

⚠️ 升级/重建前务必同时备份这两个卷：linkstack-data 丢了等于丢了 .env（含 APP_KEY）与主题；linkstack-db 丢了业务数据。docker compose down（不带 -v）不会删卷。

六、环境变量表

linkstack 服务支持的官方环境变量共 7 个（默认值取自镜像入口脚本 /usr/local/bin/docker-entrypoint.sh，2026-11-02 实测）：

变量默认值本文取值作用与生效方式
SERVER_ADMINyou@example.comadmin@quzuo.netApache ServerAdmin，写入 /etc/apache2/httpd.conf 与 conf.d/ssl.conf
HTTP_SERVER_NAMElocalhostlocalhostHTTP 虚拟主机 ServerName
HTTPS_SERVER_NAMElocalhostlocalhostHTTPS 虚拟主机 ServerName
LOG_LEVELinfoinfoApache LogLevel
TZUTCAsia/ShanghaiPHP date.timezone，追加进 /etc/php83/conf.d/40-custom.ini
PHP_MEMORY_LIMIT256M256MPHP memory_limit，同上
UPLOAD_MAX_FILESIZE8M16MPHP upload_max_filesize（主题 zip、头像上传上限），同上

生效验证（实测）：

docker compose exec linkstack php83 -i | grep -E '^(memory_limit|upload_max_filesize|date.timezone)'

memory_limit => 256M => 256M
upload_max_filesize => 16M => 16M
date.timezone => Asia/Shanghai => Asia/Shanghai

⚠️ 实测坑：入口脚本用 echo ... >> 40-custom.ini 追加写入这三项，每次重启都追加一组。重启一次后实测 tail -4 /etc/php83/conf.d/40-custom.ini 可见重复行（PHP 取最后一条，功能不受影响，但该文件会随重启不断变长）。长期运行可定期清理重复行，或在编排里改为 bind mount 一份固定的 40-custom.ini。

db 服务用 MariaDB 官方镜像标准变量初始化：MARIADB_ROOT_PASSWORD、MARIADB_DATABASE、MARIADB_USER、MARIADB_PASSWORD，与向导第 4 步填写的五要素一一对应。

七、配置参数说明

应用级配置（功能开关、注册策略、页脚显示等几十个参数）不在环境变量里，而是由向导写入 /htdocs/.env。本文部署后实测生成的数据库相关段落：

docker compose exec linkstack grep -E '^DB_' /htdocs/.env

实测输出：

DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=linkstack
DB_USERNAME=linkstack
DB_PASSWORD=q1w2e3r4

DB_CONNECTION=mysql 即第 3 步选型的落盘结果；若当初选 SQLite，这里会是 DB_CONNECTION=sqlite 且无其余四项。.env 的完整分组（注册/页脚/更新器/邮件/主题/安全等）与逐项实测见《LinkStack 4.8.8 配置参数详解》。

⚠️ 注意：.env 中数据库段落上方有官方注释警告——"Should be left alone. If you wish to use mysql you'd have to seed the database again"：装完后再把 SQLite 改成 MySQL（或反之），旧数据不会自动搬迁，必须重跑迁移并重新播种，生产环境严禁直接改库类型。

八、配置文件挂载

各配置文件位置与外置方法：

  • 应用配置 .env：位于 /htdocs/.env，/htdocs 已整体挂卷（第五章），天然持久化；如需版本化管理，可改为 bind mount 单文件： 
    # linkstack 服务的 volumes 中追加（与 - linkstack-data:/htdocs 二选一或叠加具体路径）
  volumes:
    - ./linkstack.env:/htdocs/.env
    首次可导出底稿：docker compose cp linkstack:/htdocs/.env ./linkstack.env；
  • 高级配置：/htdocs/config/advanced-config.php（分析代码注入、自定义 meta 标签等），同在卷内；管理后台有在线文件编辑器（路由 admin/advanced-config、admin/env），改完即写盘；
  • Apache 配置：/etc/apache2/httpd.conf 与 /etc/apache2/conf.d/ssl.conf 在镜像内、不持久，入口脚本每次启动按第六章环境变量表重新注入——自定义 Apache 配置需重建镜像或 bind mount 覆盖对应文件；
  • PHP 配置：/etc/php83/php.ini 与 /etc/php83/conf.d/（含追加式 40-custom.ini，见第六章注意项）；
  • HTTPS 证书：/etc/ssl/apache2/server.pem / server.key，镜像自带自签名证书（启动日志实测 AH01906 ... server certificate is a CA certificate 警告即来自它），生产建议前置反向代理终止 TLS，或挂载真实证书覆盖这两个文件。

九、等价 docker run（单服务形态）

不用 Compose 时，应用本体可等价拆成官方 README 形态的单条命令（数据库指向外部现成 MariaDB/MySQL）：

docker volume create linkstack
docker run -d --name linkstack-4-8-8 \
  --hostname linkstack \
  -e SERVER_ADMIN="admin@quzuo.net" \
  -e HTTP_SERVER_NAME="localhost" \
  -e HTTPS_SERVER_NAME="localhost" \
  -e LOG_LEVEL="info" \
  -e TZ="Asia/Shanghai" \
  -e PHP_MEMORY_LIMIT="256M" \
  -e UPLOAD_MAX_FILESIZE="16M" \
  -p 8132:80 \
  -p 8134:443 \
  --restart unless-stopped \
  -v linkstack:/htdocs \
  linkstackorg/linkstack:v4.8.8

参数与 Compose 逐项对应（端口、7 个环境变量、/htdocs 卷）。区别：数据库需已有现成实例，向导第 4 步填其真实地址与端口。装后验证与 4.6/4.7 完全一致。适用场景：数据库由 DBA 独立运维、只需部署应用本体的环境。

十、常用运维命令

以下命令均在部署目录内执行（cd /opt/linkstack-stack）：

# 查看服务状态与健康
docker compose ps

# 查看/跟踪应用日志（Apache 错误日志直接进 stderr，LogLevel=info 时含访问期告警）
docker compose logs linkstack
docker compose logs -f linkstack

# 重启应用（实测回显见下）
docker compose restart linkstack

# 进入应用排查（注意 PHP 二进制名是 php83，见第十一章 Q1）
docker compose exec linkstack sh

# 进数据库
docker compose exec db mariadb -ulinkstack -pq1w2e3r4 linkstack

# 升级版本：改 docker-compose.yml 中镜像 tag（如 v4.8.8 → 新版本）后
docker compose pull linkstack
docker compose up -d linkstack

# 升级后补跑迁移（在应用内执行）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan migrate --force'

# 停止/启动整套服务（保留数据卷）
docker compose stop
docker compose start

# 彻底销毁（含网络；加 -v 连数据卷一起删，慎用）
docker compose down
docker compose down -v

docker compose restart linkstack 实测输出：

 Container linkstack-4-8-8-stack-linkstack-1 Restarting 
 Container linkstack-4-8-8-stack-linkstack-1 Started

升级另有第二条路径：管理后台收到新版本通知后的一键更新器（自动备份到 /htdocs/backups/ 后覆盖升级，SKIP_UPDATE_BACKUP=true 可跳过备份，不建议）。

十一、常见问题

Q1：进应用执行 php artisan ... 报 php: not found？

实测现象：

sh: line 0: php: not found

定位：Alpine 的 PHP 包把 CLI 二进制装成带版本号的 /usr/bin/php83，PATH 里没有裸 php。解决：一律用 php83，如 cd /htdocs && php83 artisan --version 实测输出 Laravel Framework 9.52.22。

Q2：装完后访问 /dashboard 被弹回登录页？

实测：Finish setup 后 GET /dashboard 返回 302，Location: http://127.0.0.1:8132/login。安装会话结束、要求正式登录属预期，用向导第 5 步创建的账号（本文 root@quzuo.net / q1w2e3r4）登录即可（登录验证见 4.7）。

Q3：php83 artisan backup:run 失败，报 sqlite3: not found？

实测报错（节选）：

Starting backup...
Dumping database linkstack...
Backup failed because The dump process failed with a none successful exitcode.
Exitcode
========
127: Command not found
Error Output
============
sh: line 1: sqlite3: not found

定位：镜像默认按 SQLite 形态设计，/htdocs/config/backup.php 的 databases 列表硬编码为 ['sqlite']（实测第 84 行），MySQL 部署时它仍去调不存在的 sqlite3。解决两步：

# 1. 把备份连接改为 mysql
docker compose exec -u root linkstack sh -c "sed -i \"s/'sqlite',/'mysql',/\" /htdocs/config/backup.php"
# 2. 应用内补装 MySQL dump 客户端（Alpine 包名 mariadb-client，提供 mysqldump）
docker compose exec -u root linkstack apk add --no-cache mariadb-client

重跑实测输出（尾部）：

Zipping 10722 files and directories...
Created zip containing 10722 files and directories. Size is 21.42 MB
Copying zip to disk named backups...
Successfully copied zip to disk named backups.
Backup completed!

残留一行 Sending notification failed 无害——镜像未配置备份通知渠道，不影响产物。注意 apk 装的包在删除重建后丢失，固化需自建衍生镜像；config/backup.php 在 /htdocs 卷内、改一次即持久。

Q4：把 .env 的 FORCE_HTTPS 改成 true，HTTP 访问并没有跳转 HTTPS？

实测：改后 GET / 仍 200，但响应头新增 Content-Security-Policy: upgrade-insecure-requests。读源码定位（app/Http/Middleware/Headers.php）：FORCE_HTTPS 只做 URL 生成强制 https + CSP 头；真正 302 强跳的是另一开关 FORCE_ROUTE_HTTPS，实测置 true 后：

HTTP/1.1 302 Found
Location: https://127.0.0.1/

两开关语义不同，按需启用（详见《LinkStack 4.8.8 配置参数详解》）。

Q5：向导第 4 步填完连接参数停在 /mysql-test 不前进？

该页会真实测试数据库连通性，失败即停留报错。排查顺序：① docker compose ps 确认 db 为 Healthy；② 从应用侧连通性——docker compose exec linkstack sh -c 'nc -zv db 3306'；③ 核对填写值与编排一致（host 必须是 Compose 服务名 db，不是 localhost/127.0.0.1——指向应用自己的回环必然连不上，这是 Compose 部署最常见的填错点）；④ 库必须为空（非空会建表冲突）。

Q6：响应头/后台显示 APP_DEBUG=true，生产要不要关？

实测向导生成的 .env 默认 APP_DEBUG=true、APP_ENV=local（官方注释："useful for troubleshooting"）。生产建议改 APP_DEBUG=false、APP_ENV=production 并重启应用，避免报错页泄露路径与 SQL（改法见《LinkStack 4.8.8 配置参数详解》）。

十二、参考链接

  • 源码仓库：https://github.com/LinkStackOrg/LinkStack（v4.8.8，2026-10-22）
  • 官方 Docker 仓库：https://github.com/LinkStackOrg/linkstack-docker
  • 官方镜像（Docker Hub）：https://hub.docker.com/r/linkstackorg/linkstack
  • 官网与主题目录：https://linkstack.org/（在线演示 https://linksta.cc）
  • 本文实测记录：2026-11-02，LinkStack v4.8.8 + MariaDB 11.4，Ubuntu 22.04 宿主机
LinkStack 4.8.8 Docker Compose 部署指南 - Quzuo