netbox/NetBox前端定制化指南.md

NetBox 前端定制化指南

本文档详细说明了如何自定义 NetBox 项目的前端元素，包括网站标题、LOGO、品牌元素等。

1. 页面标题修改

1.1 基础模板标题

文件位置: netbox/templates/base/base.html 修改行: 第 23 行

<!-- 原始代码 -->
<title>{% block title %}{% trans "Home" %}{% endblock %} | NetBox</title>

<!-- 修改为 -->
<title>{% block title %}{% trans "Home" %}{% endblock %} | 您的公司名称</title>

1.2 浏览器标签页图标 (Favicon)

文件位置: netbox/templates/base/base.html 修改行: 第 45 行

<!-- 原始代码 -->
<link rel="icon" type="image/png" href="{% static 'netbox.ico' %}" />

<!-- 需要替换的文件 -->

需要替换的文件: netbox/project-static/img/netbox.ico

1.3 移动端图标

文件位置: netbox/templates/base/base.html 修改行: 第 46 行

<!-- 原始代码 -->
<link rel="apple-touch-icon" type="image/png" href="{% static 'netbox_touch-icon-180.png' %}" />

需要替换的文件: netbox/project-static/img/netbox_touch-icon-180.png

2. LOGO 修改

2.1 主导航栏 LOGO

文件位置: netbox/templates/base/layout.html 修改行: 第 32-35 行

<!-- 原始代码 -->
<h1 class="navbar-brand pb-0">
  <a href="{% url 'home' %}">
    <img src="{% static 'logo_netbox_dark_teal.svg' %}" alt="{% trans "NetBox Logo" %}" class="navbar-brand-image hide-theme-dark">
    <img src="{% static 'logo_netbox_bright_teal.svg' %}" alt="{% trans "NetBox Logo" %}" class="navbar-brand-image hide-theme-light">
    <div class="netbox-edition fw-semibold text-center fs-5 my-1">{{ settings.RELEASE.edition }}</div>
  </a>
</h1>

<!-- 修改为 -->
<h1 class="navbar-brand pb-0">
  <a href="{% url 'home' %}">
    <img src="{% static 'your_logo_dark.svg' %}" alt="您的公司 Logo" class="navbar-brand-image hide-theme-dark">
    <img src="{% static 'your_logo_light.svg' %}" alt="您的公司 Logo" class="navbar-brand-image hide-theme-light">
    <div class="netbox-edition fw-semibold text-center fs-5 my-1">您的版本信息</div>
  </a>
</h1>

需要替换的文件:

• netbox/project-static/img/logo_netbox_dark_teal.svg (深色主题下的 LOGO)
• netbox/project-static/img/logo_netbox_bright_teal.svg (浅色主题下的 LOGO)

2.2 商业版装饰图案 (可选)

文件位置: netbox/templates/base/layout.html 修改行: 第 22-24 行

<!-- 原始代码 -->
{% if settings.RELEASE.features.commercial %}
  <img class="motif" src="{% static 'motif.svg' %}" alt="{% trans "NetBox Motif" %}">
{% endif %}

需要替换的文件: netbox/project-static/img/motif.svg

3. 静态资源文件位置

3.1 图片资源目录

主要目录: netbox/project-static/img/

包含的文件:

• logo_netbox_bright_teal.svg - 浅色主题 LOGO
• logo_netbox_dark_teal.svg - 深色主题 LOGO
• motif.svg - 装饰图案
• netbox.ico - 网站图标
• netbox_icon.svg - NetBox 图标
• netbox_touch-icon-180.png - 移动端图标
• plugin-default.svg - 插件默认图标
• rest-api.ico - REST API 图标

3.2 编译后的静态资源

目录: netbox/project-static/dist/

• 包含编译后的 CSS、JS 和字体文件
• 修改源文件后需要重新编译

4. 样式定制

4.1 CSS 源文件

主要文件: netbox/project-static/styles/netbox.scss 变量文件: netbox/project-static/styles/_variables.scss

4.2 自定义样式

目录: netbox/project-static/styles/custom/

• 可以在此目录添加自定义样式文件

5. 配置文件修改

5.1 横幅配置

文件位置: netbox/configuration.py (需要创建)

可配置的横幅选项:

# 登录页面横幅
BANNER_LOGIN = "欢迎使用您的网络管理系统"

# 维护模式横幅  
BANNER_MAINTENANCE = "系统正在维护中，功能可能受限"

# 页面顶部横幅
BANNER_TOP = "您的公司内部网络管理系统"

# 页面底部横幅
BANNER_BOTTOM = "© 2024 您的公司名称"

5.2 REST API 文档标题

文件位置: netbox/netbox/settings.py 修改行: 第 733 行

# 原始代码
'TITLE': 'NetBox REST API',

# 修改为
'TITLE': '您的公司 REST API',

6. 版本信息定制

6.1 版本显示

文件位置: netbox/templates/base/layout.html 修改行: 第 52-58 行

<!-- 原始代码 -->
<div class="text-muted text-center fs-5 my-3">
  {{ settings.RELEASE.name }}
  {% if not settings.RELEASE.features.commercial and not settings.ISOLATED_DEPLOYMENT %}
    <div>
      <a href="https://netboxlabs.com/netbox-cloud/" class="text-muted">{% trans "Get" %} Cloud</a> |
      <a href="https://netboxlabs.com/netbox-enterprise/" class="text-muted">{% trans "Get" %} Enterprise</a>
    </div>
  {% endif %}
</div>

<!-- 可以修改为 -->
<div class="text-muted text-center fs-5 my-3">
  您的系统版本信息
  <!-- 移除或修改商业链接 -->
</div>

7. 搜索框定制

7.1 搜索占位符

文件位置: netbox/templates/base/layout.html 修改行: 第 75 行

<!-- 原始代码 -->
<input type="text" name="q" value="" class="form-control" placeholder="Search…" aria-label="Search NetBox">

<!-- 修改为 -->
<input type="text" name="q" value="" class="form-control" placeholder="搜索..." aria-label="搜索您的系统">

8. 实施步骤

8.1 准备工作

1. 备份原始文件
2. 准备您的 LOGO 文件 (建议使用 SVG 格式)
3. 准备网站图标文件

8.2 文件替换

1. 将您的 LOGO 文件复制到 netbox/project-static/img/ 目录
2. 修改模板文件中的引用路径
3. 更新配置文件

8.3 重新编译 (如果修改了样式)

cd netbox/project-static
npm install  # 如果是首次编译
npm run build

8.4 重启服务

# 重启 NetBox 服务以应用更改
sudo systemctl restart netbox

9. 注意事项

1. 备份: 修改前请备份原始文件
2. 版本升级: NetBox 升级时可能会覆盖自定义内容，需要重新应用修改
3. 图片格式: 建议使用 SVG 格式的 LOGO，支持响应式和主题切换
4. 缓存: 修改后可能需要清除浏览器缓存才能看到效果
5. 权限: 确保 Web 服务器对静态文件有读取权限

10. 文件清单

需要修改或替换的主要文件:

模板文件

• netbox/templates/base/base.html - 页面标题和图标
• netbox/templates/base/layout.html - LOGO 和布局

静态资源文件

• netbox/project-static/img/logo_netbox_dark_teal.svg
• netbox/project-static/img/logo_netbox_bright_teal.svg
• netbox/project-static/img/netbox.ico
• netbox/project-static/img/netbox_touch-icon-180.png
• netbox/project-static/img/motif.svg (可选)

配置文件

• netbox/configuration.py - 横幅和基本配置
• netbox/netbox/settings.py - API 文档标题

通过以上修改，您可以将 NetBox 完全定制为您自己的品牌形象。