Sun-Panel 项目部署
【摘要】 一、功能概览类别说明内外网切换每个卡片可同时配置内网地址和外网地址,一键切换访问方式分组与排序卡片分组,支持拖拽排序图标丰富文字图标、SVG 图标、内置第三方图标库,可自由搭配内置小窗口点击卡片可在页面内的小窗口中打开(部分网站禁止被嵌入,会无法显示)外观定制背景、主题、布局可调整,也支持自定义样式多账号支持账号体系,可管理用户轻量无需连接外部数据库,默认使用 SQLite,资源占用很小多...
一、功能概览
| 类别 | 说明 |
|---|---|
| 内外网切换 | 每个卡片可同时配置内网地址和外网地址,一键切换访问方式 |
| 分组与排序 | 卡片分组,支持拖拽排序 |
| 图标丰富 | 文字图标、SVG 图标、内置第三方图标库,可自由搭配 |
| 内置小窗口 | 点击卡片可在页面内的小窗口中打开(部分网站禁止被嵌入,会无法显示) |
| 外观定制 | 背景、主题、布局可调整,也支持自定义样式 |
| 多账号 | 支持账号体系,可管理用户 |
| 轻量 | 无需连接外部数据库,默认使用 SQLite,资源占用很小 |
| 多架构 | Docker 镜像对 ARM 系统友好,群晖、威联通、树莓派等设备都能跑 |
资源参考:第三方托管页给出的参考配置是 1 核 CPU、128MB 内存可运行,建议 256MB,磁盘 1GB 起步,上传大量图标或壁纸时再适当增加。
二、部署方案选择
| 方案 | 适用场景 | 说明 |
|---|---|---|
| Docker 单命令 | 快速部署 | 最简单,适合大多数人 |
| Docker Compose | 长期使用、便于迁移 | 推荐,配置可版本化管理 |
| 二进制直接运行 | 不使用 Docker 的环境 | 下载发布包,赋予执行权限后运行 |
| NAS 图形界面部署 | 群晖、威联通、绿联、极空间等 | 在套件的 Docker 界面中按下文参数填写 |
三、环境要求
- 一台常开设备:服务器、NAS、软路由或树莓派
- Docker Engine(使用 Docker 方案时)
- 默认端口:3002
- 需要在外网访问时,准备域名与 HTTPS 反向代理,或使用内网穿透、VPN
四、Docker 部署
4.1 目录说明
容器内可挂载的目录:
| 容器目录 | 说明 | 是否建议挂载 |
|---|---|---|
| /app/conf | 配置文件 | 建议 |
| /app/uploads | 上传的图标、壁纸等文件 | 建议 |
| /app/database | 数据库文件 | 必须,否则数据会丢 |
| /app/runtime | 运行日志 | 官方不推荐挂载 |
4.2 Docker 单命令
docker pull hslr/sun-panel
docker run -d --restart=always -p 3002:3002 \
-v ~/docker_data/sun-panel/conf:/app/conf \
-v ~/docker_data/sun-panel/uploads:/app/uploads \
-v ~/docker_data/sun-panel/database:/app/database \
--name sun-panel \
hslr/sun-panel
4.3 Docker Compose(推荐)
创建目录与配置文件:
mkdir -p ~/sun-panel && cd ~/sun-panel
docker-compose.yml:
services:
sun-panel:
image: hslr/sun-panel:latest
container_name: sun-panel
restart: always
ports:
- "3002:3002"
volumes:
- ./conf:/app/conf
- ./uploads:/app/uploads
- ./database:/app/database
# 如需在面板中使用 Docker 相关功能,才挂载下面这一行,见安全说明
# - /var/run/docker.sock:/var/run/docker.sock
启动:
docker compose up -d
docker compose ps
docker compose logs -f sun-panel
要点:
- 生产环境建议把镜像标签固定到具体版本号,按需升级。
- 如果要通过反向代理对外提供服务,把端口映射改为只监听本机(
127.0.0.1:3002:3002)。 - 在 NAS 图形界面部署时,同样是映射 3002 端口,并把上面三个目录映射到 NAS 的共享文件夹。
4.4 Docker 套接字的安全说明
部分第三方示例会挂载 /var/run/docker.sock,目的是让面板获得 Docker 相关的能力。请注意:
- 能访问 Docker 套接字,约等于拥有宿主机的高权限。
- 不需要这些功能就不要挂载,仅作为导航页使用完全不需要它。
- 如果确实要用,必须保证登录入口是受保护的,并且面板不要直接暴露到公网。
五、首次登录与安全设置
- 浏览器访问「服务器IP地址:3002」。
- 使用官方默认账号登录:账号
admin@sun.cc,密码12345678。 - 登录后立即修改账号邮箱和密码。默认账号密码是公开信息,不改等于没设防。
- 官方演示站也提示:不要把默认账号长期用于公开场景。
忘记密码怎么办
官方提供命令行重置第一个用户的密码:
# Docker 环境
docker exec -it sun-panel ./sun-panel -password-reset
执行后会输出用户名和重置后的密码(官方示例中重置为 12345678),登录后请马上再次修改。
命令参数:
| 参数 | 说明 |
|---|---|
| -h | 查看命令说明 |
| -config | 生成配置文件(conf/conf.ini) |
| -password-reset | 重置第一个用户的密码 |
六、配置文件
配置文件位于挂载的 conf 目录,核心文件是 conf.ini,可通过 -config 参数生成。常见配置项:
[base]
# 服务监听端口,默认 3002
http_port=3002
# 数据库驱动:sqlite(默认)或 mysql
database_drive=sqlite
说明:
- 绝大多数个人场景使用默认的 SQLite 即可,无需额外数据库。
- 如需改用 MySQL,除了切换驱动,还需要填写数据库连接信息,具体字段请对照生成出来的配置文件里的注释。
- 修改配置后需要重启容器才会生效:
docker compose restart sun-panel。
七、日常使用建议
7.1 规划卡片
- 先分组再添加:按用途分组,例如「媒体」「下载」「运维」「文档」「常用网站」。
- 同时填写内外网地址:在家用内网地址,出门用外网地址,一键切换。
- 善用图标库:内置图标库不够用时,可以上传自己的图标。
- 注意小窗口限制:部分网站不允许被嵌入,打不开时改用新标签页打开。
7.2 外观定制
- 面板支持背景图、主题和布局调整。
- 如果使用自定义 CSS 或 JS,只引用你信任的代码。自定义脚本会在每个访问者的浏览器里执行,从来源不明的地方复制来的脚本可能带来安全风险,尤其是当你的面板对外开放时。
7.3 作为浏览器首页
把浏览器的主页设置为面板的访问地址即可。对外使用时建议配合 HTTPS 与账号保护。
八、反向代理与 HTTPS
Caddy 示例:
nav.你的域名 {
encode zstd gzip
reverse_proxy 127.0.0.1:3002
}
使用 Nginx 时,常规的反向代理配置即可,如面板中有较大的图片上传,适当调大请求体大小限制。
对外开放的安全建议:
- 使用 HTTPS,并修改默认账号密码。
- 导航页里往往列出了你全部内部服务的地址,一旦公开就等于给了外人一张地图。如果不需要外网访问,就只在内网使用;需要外网访问时,优先通过 VPN 或带认证的网关接入。
- 卡片里不要填写含有密码或令牌的链接。
九、备份、迁移与升级
9.1 备份
需要备份的三个目录:
| 目录 | 内容 |
|---|---|
| conf | 配置文件 |
| database | 全部卡片、分组、账号等数据 |
| uploads | 上传的图标与壁纸 |
cd ~/sun-panel
tar czf sun-panel-backup-$(date +%F).tar.gz conf database uploads
建议先停止容器再备份,保证数据库文件一致;备份文件同步到另一台设备或云存储,遵循 3-2-1 原则:3 份副本、2 种介质、1 份异地。
9.2 迁移
在新机器上部署相同方案,把上面的三个目录复制过去,启动即可,数据完整保留。
9.3 升级
cd ~/sun-panel
docker compose pull
docker compose up -d
docker image prune
建议:
- 升级前先备份。
- 固定镜像版本,查看更新说明后再升级。
- 项目为个人开发者维护,更新节奏可能不固定,选用前可以看一下仓库近期的活跃度。
十、常见问题排查
| 现象 | 可能原因 | 处理办法 |
|---|---|---|
| 访问不了 3002 端口 | 端口未映射或被防火墙拦截 | 检查映射与防火墙,确认端口没被占用 |
| 默认账号登录失败 | 已修改过账号密码 | 使用你修改后的账号,或执行密码重置命令 |
| 重启后数据丢失 | 没有挂载 database 目录 | 确认三个目录都已挂载到宿主机 |
| 小窗口打开网站显示空白 | 目标网站禁止被嵌入 | 改用新标签页打开 |
| 外网访问样式异常或加载慢 | 反向代理配置问题 | 检查代理转发与协议头 |
| 上传图片失败 | 目录权限或请求体限制 | 检查 uploads 目录权限,调大代理限制 |
| 修改配置不生效 | 未重启容器 | 重启容器让配置生效 |
| 数据库权限错误 | 挂载目录属主不匹配 | 调整目录所有者,或在 NAS 上给予读写权限 |
| 自定义脚本导致页面异常 | 脚本有错误或与前端冲突 | 在设置中暂时移除自定义脚本,逐项排查 |
十一、命令速查
# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart sun-panel
# 查看日志
docker compose logs -f sun-panel
# 重置第一个用户的密码
docker exec -it sun-panel ./sun-panel -password-reset
# 生成配置文件
docker exec -it sun-panel ./sun-panel -config
# 备份
tar czf sun-panel-backup-$(date +%F).tar.gz conf database uploads
# 升级
docker compose pull && docker compose up -d
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)