LinkStack 4.8.8 配置参数详解

目标：系统梳理 LinkStack 4.8.8 的三层配置体系——Docker 环境变量（Apache/PHP 层）、/htdocs/.env（应用行为层，40+ 项逐组讲解）、/htdocs/config/advanced-config.php（首页 meta/分析代码/自定义按钮层），给出安装向导选项与 .env 的落盘映射，并完成 8 项功能开关的端到端实测（改 .env 即时生效、无需重启）。已在 Ubuntu 22.04（x86_64）服务器、LinkStack 4.8.8（MariaDB 11.4 系统库）上全量实测通过。部署过程见《LinkStack 4.8.8 Docker Compose 部署指南》。

一、环境信息

• 组件版本：LinkStack v4.8.8（官方镜像 linkstackorg/linkstack:v4.8.8，2026-10-22）
• 应用内技术栈：Alpine Linux + Apache 2.4.69 + PHP 8.3.36 + Laravel Framework 9.52.22
• 系统数据库：MariaDB 11.4（向导按 MySQL 类型接入）
• 部署形态：Docker Compose 编排（见上篇部署指南）
• 访问入口：http://<服务器IP>:8132/（HTTPS 自签名 https://<服务器IP>:8134/）
• 管理账号：root@quzuo.net / q1w2e3r4，主页句柄 @root
• 参数依据：实例内 /htdocs/.env 全文（144 行，实测导出）+ /htdocs/config/advanced-config.php 全文（189 行）+ 4.8.8 源码行为
• 实测日期：2026-11-02

二、配置体系总览：三层落点

LinkStack 的配置按"谁消费"分三层，优先级互不重叠（各管各的层面）：

后台提供两个官方在线编辑器（实测路由表）：

docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan route:list' | grep -iE 'env|advanced'

实测输出（节选）：

  GET|HEAD        admin/advanced-config showFileEditor › AdminController@show…
  POST            admin/advanced-config ...... editAC › AdminController@editAC
  GET|HEAD        admin/env .. showFileEditor › AdminController@showFileEditor
  POST            admin/env ................ editENV › AdminController@editENV
  GET|HEAD        env-editor env-editor.index › GeoSot\EnvEditor › EnvControl…
  POST            env-editor/files/create-backup env-editor.createBackup › Ge…

即：管理后台 /#/dashboard/admin/env 直接编辑 .env、admin/advanced-config 编辑高级配置；另捆绑 GeoSot/laravel-env-editor 包（/env-editor 一族路由），支持 .env 备份/下载/回滚——改配置前建议先在该页创建备份。

💡 技术拓展：.env 是 Laravel 体系的标准环境变量文件，框架启动时经 vlucas/phpdotenv 读入，config/*.php 里的 env('KEY', 默认值) 调用即取自此处。它与 Docker 环境变量的区别：后者只被镜像入口脚本消费（写 Apache/PHP 配置文件），不会自动进 .env；改容器变量不会动应用配置，反之亦然。

三、应用层 .env 分组速查

实测导出 /htdocs/.env 共 144 行，按官方注释分 10 组：

四、安装向导选项 → .env 落盘映射

上篇部署指南 4.5 节走通的六步向导，本质是往 .env 写值（实测对照）。落盘命令面为 POST /editConfigInstaller（entry/value 键值对）与数据库/管理员各步进接口：

第 5 步管理员账号不进 .env，直接落 users 表（邮箱 root@quzuo.net、口令哈希、句柄 root）。

五、功能开关逐项实测（即时生效，无需重启）

LinkStack 无法执行 php83 artisan config:cache（实测 fatal，见《LinkStack 4.8.8 常用 CLI 命令与工具详解》排障节），配置每请求现读，因此改 .env 后无需重启容器即可验证——这是本文全部开关实测的基础。

通用验证方法：容器内 sed -i 改值 → 宿主机 curl 页面 grep 特征串 → 改回。特征串来自读模板源码（footer.blade.php 页脚容器类名 footer-hover、"Powered by LinkStack" 徽标类名 powered-by-linkstack）。

5.1 DISPLAY_FOOTER（用户页页脚）

实测（开→关→开）：

docker compose exec linkstack sh -c "sed -i 's/^DISPLAY_FOOTER=true/DISPLAY_FOOTER=false/' /htdocs/.env && grep '^DISPLAY_FOOTER=' /htdocs/.env"
curl -s http://127.0.0.1:8132/@root | grep -c 'footer-hover'

实测输出：

DISPLAY_FOOTER=false
0

改回 true 后同一命令输出 1。⚠️ 实测坑：该开关只在用户主页（/@root）生效，默认首页（LinkStack 落地页）源码不渲染该页脚，在首页 grep 恒为 0，验证时务必访问用户页。

5.2 DISPLAY_CREDIT（"Powered by LinkStack" 署名）

docker compose exec linkstack sh -c "sed -i 's/^DISPLAY_CREDIT=true/DISPLAY_CREDIT=false/' /htdocs/.env"
curl -s http://127.0.0.1:8132/@root | grep -c 'powered-by-linkstack'

实测输出：0（默认 true 时为 1）。同类还有 DISPLAY_CREDIT_FOOTER（页脚区署名，默认 true，机制同上）。

5.3 FORCE_HTTPS 与 FORCE_ROUTE_HTTPS（易混的一对）

FORCE_HTTPS=true 实测响应头：

docker compose exec linkstack sh -c "sed -i 's/^FORCE_HTTPS=false/FORCE_HTTPS=true/' /htdocs/.env"
curl -sI http://127.0.0.1:8132/ | grep -iE '^HTTP|content-security'

HTTP/1.1 200 OK
Content-Security-Policy: upgrade-insecure-requests

页面不跳转，只做两件事：应用内生成的 URL 强制 https 方案 + 下发 CSP upgrade-insecure-requests 头（源码 app/Http/Middleware/Headers.php）。.env 官方注释还提示：Docker 镜像形态下该头只影响 443 端口。

FORCE_ROUTE_HTTPS=true 才是 302 强跳：

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

（实测请求 Host: 127.0.0.1:8132，跳转保留原 host:port；改回 false 后恢复 HTTP/1.1 200 OK。）生产经反向代理终止 TLS 时，通常两个都不开、由代理层做跳转，仅设 APP_URL 为 https 域名。

5.4 ALLOW_REGISTRATION（开放注册）

docker compose exec linkstack sh -c "sed -i 's/^ALLOW_REGISTRATION=true/ALLOW_REGISTRATION=false/' /htdocs/.env"
curl -s http://127.0.0.1:8132/login | grep -oiE 'register' | sort | uniq -c
curl -s -o /dev/null -w 'POST /register http=%{http_code}\n' -X POST http://127.0.0.1:8132/register -d "name=x"

实测输出：

POST /register http=302

登录页 grep register 零命中（默认 true 时命中 1 处注册链接），直接 POST /register 被 302 弹走。改回 true 后登录页恢复注册链接（1 register）。

5.5 REGISTER_AUTH（邮箱验证策略）

auth=注册即用（向导"Enable email verification"选 No 的落盘值）；verified=新账号须点邮件验证链接才可登录。它决定验证邮件是否必发，因此与第五章 Mail 组联动：选 verified 而邮件通道不通时，新注册用户会卡在未验证状态（管理员可在后台手工置已验证，对应 MANUAL_USER_VERIFICATION=true）。

5.6 MAINTENANCE_MODE（维护模式）

docker compose exec linkstack sh -c "sed -i 's/^MAINTENANCE_MODE=false/MAINTENANCE_MODE=true/' /htdocs/.env"
curl -s -o /dev/null -w 'GET / http=%{http_code}\n' http://127.0.0.1:8132/
curl -s http://127.0.0.1:8132/ | grep -oiE 'maintenance|down' | sort | uniq -c

实测输出：

GET / http=200
      1 maintenance
      1 Maintenance

全站关闭、渲染维护占位页（HTTP 码仍是 200，不是 Laravel 标准的 503——监控告警别指望状态码，要盯页面内容）。改回 false 后站点恢复正常 200。

5.7 APP_NAME（站点显示名）

docker compose exec linkstack sh -c "sed -i 's/^APP_NAME=\"LinkStack\"/APP_NAME=\"MyLinks\"/' /htdocs/.env"
curl -s http://127.0.0.1:8132/ | grep -oE '<title>[^<]*</title>'

实测输出（改前 <title>LinkStack</title> → 改后）：

<title>MyLinks</title>

改回后恢复 <title>LinkStack</title>。注意 MAIL_FROM_NAME="${APP_NAME}" 会跟着变；标题后缀可在 advanced-config.php 的 linkstack_title 单独定制（见第六章）。

5.8 HOME_URL（用户页设为首页）

docker compose exec linkstack sh -c "sed -i 's/^HOME_URL=/HOME_URL=root/' /htdocs/.env"
curl -s http://127.0.0.1:8132/ | grep -oE '@root' | head -3

实测输出：

@root
@root
@root

访问 / 直接渲染句柄 root 的主页（值不带 @）。改回空值恢复默认首页。配套：高级配置 custom_home_url（默认 /home）——设了 HOME_URL 后，默认首页被"让位"到这个内部路由。

六、advanced-config.php（高级配置）详解

实测导出全文 189 行，'version' => '2.1'（勿改）。各段与默认值：

七、其余参数组速查

7.1 应用基础与安全

7.2 数据库（勿轻动）

实测落盘：

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

.env 官方注释原文警告："Should be left alone. If you wish to use mysql you'd have to seed the database again"——装完再切库类型（SQLite↔MySQL）不搬数据，必须重跑迁移+重新播种。SQLite 形态只有 DB_CONNECTION=sqlite 一行，库文件在卷内 /htdocs/database/。

7.3 用户与内容

7.4 通知、更新器与主题

7.5 邮件

7.6 框架杂项（保持默认即可）

LOG_CHANNEL=stack、LOG_LEVEL=debug（生产建议 warning，日志在 /htdocs/storage/logs/）、CACHE_DRIVER=file、SESSION_DRIVER=file、SESSION_LIFETIME=120（分钟）、QUEUE_CONNECTION=sync、BROADCAST_DRIVER=log、MEMCACHED_HOST=127.0.0.1、REDIS_HOST=127.0.0.1/REDIS_PORT=6379/REDIS_PASSWORD=null。单实例场景全部默认值合理；多实例横向扩容时才需要把缓存/会话改指 Redis。

八、生产配置建议模板

在向导装完的 .env 基础上，生产实例建议改动（其余保持默认）：

# 容器内 /htdocs 目录执行（改前先在 /env-editor 建备份）
sed -i 's/^APP_DEBUG=true/APP_DEBUG=false/' .env
sed -i 's/^APP_ENV=local/APP_ENV=production/' .env
sed -i 's/^LOG_LEVEL=debug/LOG_LEVEL=warning/' .env
sed -i 's/^ALLOW_USER_HTML=true/ALLOW_USER_HTML=false/' .env        # 多用户公开注册实例
sed -i 's/^ALLOW_CUSTOM_CODE_IN_THEMES=true/ALLOW_CUSTOM_CODE_IN_THEMES=false/' .env

HTTPS 策略：前置 Nginx/Caddy 终止 TLS 时，FORCE_HTTPS/FORCE_ROUTE_HTTPS 都保持 false，跳转交给代理；裸用镜像 443 自签证书时才考虑 FORCE_ROUTE_HTTPS=true。

九、排障实录

R1：改了 .env 感觉没生效？ 先确认访问的是对的页面：DISPLAY_FOOTER/DISPLAY_CREDIT 只作用于用户主页（5.1 实测坑）；CUSTOM_META_TAGS 组的全部 meta 覆盖需先在 .env 把 CUSTOM_META_TAGS=true 才启用（advanced-config.php 文件头注释原文）。LinkStack 无配置缓存可清——php83 artisan config:cache 在本应用会 fatal（见 CLI 篇），所以改动本就即时生效，"没生效"多为验证位置/特征串选错。

R2：FORCE_HTTPS=true 后 HTTP 访问不跳转 非故障，语义即如此（5.3 实测：只加 CSP 头，302 强跳是 FORCE_ROUTE_HTTPS）。两开关名只差一个词，是社区高频疑问。

R3：注册了收不到验证邮件 REGISTER_AUTH=verified 时验证邮件走 MAIL_MAILER 通道；默认 built-in 依赖官方中转服务，自建实例建议改 smtp 指向自己的邮件服务器并填五项连接参数（7.5 节）。临时兜底：管理员后台手工置已验证（MANUAL_USER_VERIFICATION=true）。

R4：把登录页路径改了之后自己进不去 advanced-config.php 的 login_url 改名后旧路径立即失效，须按新路径访问（第六章）；改前记下原值，误操作可直接编辑该文件改回。

十、参考链接

• 源码仓库：https://github.com/LinkStackOrg/LinkStack（v4.8.8，2026-10-22）
• 高级配置官方说明：https://llc.bio/advanced-config（.env 注释内给出的原文链接）
• 可用按钮名列表：https://linkstackorg.github.io/buttons/
• 官方 Docker 仓库：https://github.com/LinkStackOrg/linkstack-docker
• 本文实测记录：2026-11-02，LinkStack v4.8.8 + MariaDB 11.4，Ubuntu 22.04 宿主机