Focalboard 管理员指南：config.json 服务端配置详解与本地管理模式密码重置实战

Focalboard 管理员指南config.json 服务端配置详解与本地管理模式密码重置实战【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboardFocalboard 是一套开源、自托管的看板/项目管理平台个人服务器Personal Server模式下管理员的所有关键行为——监听端口、数据库选型、会话有效期、监控与共享策略——都收敛在一个config.json文件里而忘记密码这类高危运维操作则依赖独立的本地 Unix Socket 管理接口完成。本文以仓库中的 Administrators Guide 为骨架结合仓库内真实配置与 Go 源码实现完整讲解config.json的每个配置项及默认值、配置的加载机制与优先级并给出基于reset-password.sh的密码重置全流程与底层安全原理帮助你独立完成 Focalboard 个人服务器的日常管理与排障。一、个人服务器配置config.json 概览Focalboard 个人服务器的全部设置存储在config.json中服务器启动时读取该文件。仓库根目录下的 config.json 即为一份可直接运行的完整配置样例本文将以它为基准展开说明。下表完整列出了文档给出的核心配置键、含义与示例值Key说明示例serverRoot服务器的根 URLhttp://localhost:8000port服务器监听端口8000dbtype数据库类型支持sqlite3、postgres、mysqlsqlite3dbconfig数据库连接串postgres://user:passlocalhost/boards?sslmodedisableconnect_timeout10useSSL启用或禁用 SSLfalsewebpathWeb 静态文件路径./webapp/packfilespath上传文件的存储目录./filestelemetry是否启用健康诊断遥测trueprometheus_address启用 Prometheus 指标监听地址为空时禁用:9092session_expire_time会话过期时间秒2592000session_refresh_time会话刷新时间秒18000localOnly仅允许来自 localhost 的连接falseenableLocalMode在本地 Unix 端口启用管理 APItruelocalModeSocketLocation本地 Unix Socket 位置/var/tmp/focalboard_local.socketenablePublicSharedBoards是否允许将看板发布为公开访问false仓库根目录 config.json 中的实际默认配置还额外包含几个文档未列出的键它们同样会被配置结构体接收包括dbpingattempts数据库连通性探测重试次数源码默认 5见 config.godbtableprefix数据库表名前缀默认空字符串postgres_dbconfigPostgreSQL 专用连接串示例dbnamefocalboard sslmodedisablefilesdriver文件存储驱动默认local源码中还有完整的 Amazon S3 配置项filess3config见 config.gowebhook_update更新通知 Webhook 列表默认空数组authMode认证模式默认nativelogging_cfg_file/audit_cfg_file日志与审计配置文件路径默认空。1.1 配置的读取与覆盖机制配置文件由 services/config/config.go 中的ReadConfigFile函数负责解析底层使用 viper 库未显式指定路径时默认读取工作目录下的./config.json支持环境变量覆盖viper 设置了FOCALBOARD前缀并开启AutomaticEnv因此你可以用FOCALBOARD_SERVERROOT...这类环境变量覆盖 JSON 中的同名键见 config.go未在 JSON 中出现的键会回落到代码内定义的默认值。几个值得注意的默认值见 config.goPort默认8000DBType默认sqlite3DBConfigString默认./focalboard.dbSessionExpireTime默认60*60*24*30即 30 天会话生命周期SessionRefreshTime默认60*60*5即 5 分钟会话刷新窗口EnableLocalMode的代码默认值是false而仓库根目录的 config.json 显式写为true说明该能力需要管理员在配置文件中主动打开PrometheusAddress默认空字符串与文档为空即禁用的描述一致。1.2 关键配置项的语义与影响结合源码对几个容易影响部署行为的键做补充说明数据库选型dbtype / dbconfigdbtype支持sqlite3、postgres、mysql三种。SQLite 场景下连接串形如./focalboard.db?_busy_timeout5000仓库默认配置PostgreSQL 形如postgres://user:passlocalhost/boards?sslmodedisableconnect_timeout10。服务端通过sql.Open(config.DBType, config.DBConfigString)直接建立连接并在启动时执行Ping探测见 server.go配合dbpingattempts控制重试。三种数据库的完整 DDL/迁移脚本可参考 server/services/store/sqlstore 目录下的 SQL 文件。会话机制session_expire_time / session_refresh_time会话过期时间决定会话在多久后强制失效刷新时间则用于滑动续期。在 server/auth/auth.go 中服务端先按SessionExpireTime取出会话若会话最近更新时间早于SessionRefreshTime阈值则会刷新UpdateAt从而避免活跃用户被中途踢出。SSL 与访问控制useSSL / localOnlyuseSSL控制是否启用 HTTPSlocalOnly为true时服务只绑定本地回环地址仅允许本机连接适合本机单用户部署场景。监控与遥测telemetry / prometheus_addresstelemetry控制健康诊断遥测是否上报prometheus_address不为空如:9092时服务端会启动独立的 Prometheus 指标采集 HTTP 服务见 server.go 中metrics.NewMetricsServer的调用。公开分享enablePublicSharedBoards设为true后用户可将看板发布为公开链接访问默认关闭。二、重置用户密码基于本地 Unix Socket 的管理 API2.1 本地管理模式的工作原理默认情况下个人服务器会在本地 Unix Socket 上暴露管理 APISocket 默认位于/var/tmp/focalboard_local.socket。该行为由enableLocalMode与localModeSocketLocation两个配置项控制。从源码看本地管理模式是一条与常规 Web 服务完全隔离的通道在 server/server/server.go 中服务端单独创建了localRouter并通过focalboardAPI.RegisterAdminRoutes(localRouter)只注册管理类路由startLocalModeServer见 server.go使用net.Listen(unix, socket)创建 Unix 域套接字监听并执行os.Chmod(socket, 0600)将 Socket 文件权限限定为仅属主可读写防止其他系统用户滥用管理接口管理接口本身也做了双重防护adminRequired中间件会检查请求来源连接类型只有当连接是*net.UnixConn即来自本地 Unix Socket时才放行否则直接返回 401not a local unix connection见 auth.go。这意味着通过普通 HTTP 端口远程调用管理 API 是不可行的密码重置天然只能由服务器本机管理员完成。2.2 API 版本说明v1 与 v2管理 API 存在版本差异需要根据部署形态选择若你使用的是 Mattermost Boards 至 v7.1 及更早的版本需要使用 v1 版本的 API从 v7.2 起需要使用 v2 版本的 API。当前仓库的独立服务端版本使用 v2 路径。路由注册见 server/api/api.gofunc (a *API) RegisterAdminRoutes(r *mux.Router) { r.HandleFunc(/api/v2/admin/users/{username}/password, a.adminRequired(a.handleAdminSetPassword)).Methods(POST) }对应的处理函数handleAdminSetPassword见 server/api/admin.go会从 URL 变量中取出username解析请求体 JSON 中的password字段校验非空后调用a.app.UpdateUserPassword(username, requestData.Password)完成密码更新并写入审计记录adminSetPassword。2.3 使用 reset-password.sh 重置密码仓库在 server/admin-scripts/reset-password.sh 提供了现成的重置脚本完整内容如下#!/bin/bash if [[ $# 2 ]] ; then echo reset-password.sh username new password exit 1 fi curl --unix-socket /var/tmp/focalboard_local.socket http://localhost/api/v2/admin/users/$1/password -X POST -H Content-Type: application/json -d { password: $2 }使用方式与要点调用格式reset-password.sh username new password脚本要求至少两个参数否则打印用法提示并退出退出码 1。传输方式curl --unix-socket /var/tmp/focalboard_local.socket使 curl 通过本地 Unix Socket 发起请求这正是上一节所述adminRequired校验所要求的本地连接。目标地址http://localhost/api/v2/admin/users/$1/password注意路径中的/api/v2对应 v2 API若服务端为 v7.1 及以下版本需要将路径改为/api/v1/...以匹配旧版本。请求方法-X POST与路由注册的.Methods(POST)一致。请求体-d { password: $2 }以 JSON 形式携带新密码服务端AdminSetPasswordData结构体只解析password字段见 admin.go。Socket 位置脚本硬编码了默认 Socket 路径。若你在config.json中修改了localModeSocketLocation需要同步替换脚本中的路径。前提条件enableLocalMode必须为true仓库根目录 config.json 默认即开启否则本地管理 Socket 不会启动请求将失败。2.4 重置后的用户引导密码重置完成后典型场景是用户忘记密码应引导该用户从侧边栏顶部的用户菜单中点击自己的用户名进入用户菜单再通过其中的修改密码入口将临时密码更改为自己的新密码。三、运维排障提示Socket 文件残留服务端启动本地模式前会先检查 Socket 文件是否存在若存在则先Unlink再重新监听见 server.go因此正常重启不会因旧文件冲突失败但如果进程异常退出后又出现Address already in use类问题可检查/var/tmp/focalboard_local.socket是否为残留文件。权限问题Socket 文件权限为0600执行reset-password.sh的操作系统用户必须与运行 Focalboard 服务的用户一致或拥有该文件读写权限否则 curl 无法连接。远程调用必然失败任何试图通过http://服务器地址:8000/api/v2/admin/...远程调用管理 API 的请求都会被adminRequired以 401 拒绝——这是刻意设计的安全边界不是 bug。配置改动生效时机配置在服务器启动时一次性读取ReadConfigFile修改config.json后需要重启服务进程才能生效。四、小结本文完整覆盖了 Focalboard 个人服务器管理的两大核心config.json的配置项语义与加载机制含 viper 默认值与环境变量覆盖以及基于本地 Unix Socket 管理 API 的密码重置流程含 v1/v2 API 版本差异与reset-password.sh的使用。底层实现证据均可在仓库中直接查验配置结构体与默认值见 services/config/config.go管理路由注册见 api/api.go本地连接校验见 api/auth.goUnix Socket 服务启动逻辑见 server/server/server.go。掌握这些细节即可独立完成 Focalboard 服务端的部署调优与账号应急管理。【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考