企业官网建设流程全解析

• 后端

本指南以 ActiveAdmin（Ruby on Rails 应用的管理框架）的config/initializers/active_admin.rb初始化文件为核心，系统讲解认证方法、站点标题、国际化、命名空间、加载路径、资源评论、工具导航与页脚等全局配置项的用法与底层原理。阅读后你将掌握如何在应用级与命名空间级精准定制 ActiveAdmin 行为，并理解这些配置在框架源码中的落点，从而安全地应用到生产项目中。

配置文件入口与 setup 机制

ActiveAdmin 的所有通用配置都集中在应用初始化文件config/initializers/active_admin.rb中，通过ActiveAdmin.setup do |config|块完成。安装 ActiveAdmin 时由 install generator 生成该文件，其中带有大量注释说明每项配置的默认值和使用示例，是日常查阅配置项的最佳起点。

从源码结构看，配置体系分为两层：

• 应用级设置（ApplicationSettings，见 lib/active_admin/application_settings.rb）：存放default_namespace、load_paths、localize_format、filter_attributes等面向整个应用的配置。
• 命名空间级设置（NamespaceSettings，见 lib/active_admin/namespace_settings.rb）：存放site_title、current_user_method、authentication_method、route_options、default_per_page等可被每个命名空间单独覆盖的配置。

两者的注册机制都在 settings_node.rb 中实现：register(name, value)通过class_attribute声明配置属性并赋予默认值。Application类用method_missing把config.xxx = ...的赋值转发到对应的设置节点（见 application.rb），而Namespace类同样通过method_missing将命名空间块内的赋值委托给命名空间自己的设置副本（见 namespace.rb）。

认证配置：强制登录与当前用户

ActiveAdmin 依赖两个配置项来完成认证流程：

• authentication_method：控制器用来强制认证的方法（一般通过 before_action 调用）。
• current_user_method：用于获取当前登录用户的方法。

config.authentication_method = :authenticate_admin_user! config.current_user_method = :current_admin_user

使用 Devise 安装时，生成器会自动填入与 AdminUser 模型匹配的方法名：:authenticate_admin_user!与:current_admin_user（见 install 模板）。这两个方法通常定义在你的ApplicationController中。

如果希望完全关闭认证，将两者都设为false：

config.authentication_method = false config.current_user_method = false

从 namespace_settings.rb 可以看到两者的默认值均为false，也就是说只有在初始化文件中显式配置后认证才会生效。

站点标题：Site Title 选项

每个页面的菜单栏左侧都会显示站点标题（site title），默认由生成器设置为应用名（如Rails.application.class.name.split("::").first.titlecase）。你可以通过以下配置完全自定义：

config.site_title = "My Admin Site" config.site_title_link = "/" config.site_title_image = "site_image.png" config.site_title_image = "https://www.google.com/images/logos/google_logo_41.png" config.site_title_image = ->(context) { context.current_user.company.logo_url }

要点说明：

• site_title支持字符串，也支持Symbol或Proc（见 namespace_settings.rb 中注册时声明的:string_symbol_or_proc类型），动态标题场景下很有用。
• site_title_link控制点击标题跳转的 URL。
• site_title_image可以是相对路径、绝对 URL，也可以是接收视图上下文的Proc——上面第三个示例展示了根据当前登录用户动态取公司 Logo 的典型多租户用法。

国际化（I18n）与日期时间本地化

语言包与自定义翻译

ActiveAdmin 自带大量语言翻译文件，全部位于仓库的 config/locales/ 目录（包含en.yml、zh-CN.yml、ja.yml、fr.yml等 40 余种语言）。要翻译成新语言或修改现有翻译，只需把 config/locales/en.yml 复制到你自己应用的config/locales目录并修改即可。

两点注意事项：

• ActiveAdmin 不提供分页组件 kaminari 的翻译，需要额外引入kaminari-i18ngem 才能让分页文案跟随 locale 变化。仓库自带的 kaminari 分页视图模板位于 app/views/active_admin/kaminari/，供你参考其渲染结构。
• 若使用 Devise 做认证，可引入devise-i18ngem 来获得其他 locale 的认证相关翻译（如登录、找回密码页文案）。

日期与时间的本地化格式

ActiveAdmin 默认使用:long作为日期和时间的本地化格式，对应 Rails I18n 中date.formats/time.formats的长格式。你可以覆盖为其他格式：

config.localize_format = :short

该配置在 application_settings.rb 中注册，默认值:long。可运行bin/rails runner 'puts I18n.t("date.formats")'查看你的应用中可用的格式键。

命名空间：组织资源的核心单元

默认命名空间与路由

在app/admin/posts.rb中注册资源时，默认会载入admin命名空间：

# app/admin/posts.rb ActiveAdmin.register Post do # ... end

此时 Post 资源在/admin/posts下访问。从 namespace.rb 的注释和实现可以看到：命名空间决定了路由前缀（route_prefix）、控制器模块名（module_name，例如Admin::PostsController）以及该命名空间下的菜单。注册到:root命名空间（namespace: false）则意味着不启用命名空间，资源直接挂在/posts下。

默认命名空间本身也可修改，在初始化文件中设置config.default_namespace = :super_admin即可；而 application.rb 中的register方法会从options.fetch(:namespace) { default_namespace }决定资源归属。

每个命名空间独立配置

每个命名空间持有自己的设置副本，继承自应用配置（SettingsNode.build(application.namespace_settings)，见 namespace.rb）。因此可以用config.namespace(name)块为不同命名空间设置不同标题：

ActiveAdmin.setup do |config| config.site_title = "My Default Site Title" config.namespace :admin do |admin| admin.site_title = "Admin Site" end config.namespace :super_admin do |super_admin| super_admin.site_title = "Super Admin Site" end end

原则上，setup 块中可用的每一项配置都能在命名空间级别单独覆盖。

route_options：多租户与子域名挂载

多租户应用常常希望多个命名空间挂载到同一路径，借助route_options的路由约束即可实现：

config.namespace :site_1 do |admin| admin.route_options = { path: :admin, constraints: ->(request){ request.domain == "site1.com" } } end config.namespace :site_2 do |admin| admin.route_options = { path: :admin, constraints: ->(request){ request.domain == "site2.com" } } end

如果希望命名空间挂载在子域名而非路径下，同样使用route_options：

config.namespace :admin do |admin| admin.route_options = { path: '', subdomain: 'admin' } end

这些route_options最终会透传给 router.rb 中的router.namespace namespace.name, **namespace.route_options.dup调用，直接作用于 Rails 路由定义。注意:super_admin未设置route_options时，其默认值为{}（见 namespace_settings.rb）。

加载路径：改变管理文件的存放目录

默认情况下，ActiveAdmin 的资源配置文件放在app/admin/目录下。这个默认路径注册在 application_settings.rb：[File.expand_path("app/admin", Rails.root)]。你可以在初始化文件中改变它：

ActiveAdmin.setup do |config| config.load_paths = [File.join(Rails.root, "app", "ui")] end

也可以加载多个目录（比如不同角色使用不同目录）：

config.load_paths = [ File.join(Rails.root, 'app', 'admin'), File.join(Rails.root, 'app', 'cashier') ]

从 application.rb 可以看到，load!会遍历load_paths下所有**/*.rb文件并逐个加载；同时 ActiveAdmin 会把这些目录从 Rails 的autoload_paths和eager_load_paths中移除，避免常量重复加载（见 application.rb）。

资源评论（Comments）配置

ActiveAdmin 默认启用资源评论功能（页面底部可对任意资源发表评论，评论模型实现见 lib/active_admin/orm/active_record/comments.rb）。可以在三个层级控制：

# 针对整个应用： ActiveAdmin.setup do |config| config.comments = false end # 针对某个命名空间： ActiveAdmin.setup do |config| config.namespace :admin do |admin| admin.comments = false end end # 针对某个资源： ActiveAdmin.register Post do config.comments = false end

评论相关的其他配置：

# 修改评论资源注册名 config.comments_registration_name = 'AdminComment' # 修改评论排序方式与排序列 config.comments_order = 'created_at ASC' # 禁用评论索引页的菜单项 config.comments_menu = false # 自定义评论菜单 config.comments_menu = { parent: 'Admin', priority: 1 }

同时记得在需要显示评论的位置放置：

active_admin_comments_for(resource)

comments_menu的哈希形式（parent、priority）与 menu.rb 中菜单项的构建方式一致，支持挂到指定父菜单并按优先级排序。

工具导航（Utility Navigation）定制

页面右上角默认展示当前用户信息和登出链接，这部分被称为 "utility navigation"。它本质上也是一个普通菜单，因此可以完全替换为你自己的菜单：

ActiveAdmin.setup do |config| config.namespace :admin do |admin| admin.build_menu :utility_navigation do |menu| menu.add label: "ActiveAdmin.info", url: "https://www.activeadmin.info", html_options: { target: "_blank" } admin.add_current_user_to_menu menu admin.add_logout_button_to_menu menu end end end

其中build_menu会在菜单构建前把块中定义的条目注入对应菜单（见 namespace.rb），而add_current_user_to_menu与add_logout_button_to_menu是命名空间提供的辅助方法，用于恢复"当前用户 + 登出链接"的默认行为，logout_link_path配置（默认:destroy_admin_user_session_path）则控制登出链接指向。

页脚定制

默认情况下每个页面底部都会显示 "Powered by ActiveAdmin"。可以覆盖成业务相关文案：

config.footer = "MyApp Revision v1.3"

更多可探索的全局配置

除了本指南重点讲解的内容，初始化文件模板中还注释了大量常用配置，可按需启用：

• 分页：config.default_per_page = 30、config.max_per_page = 10_000（默认值定义于 namespace_settings.rb）。
• 过滤器：config.filters = true、config.include_default_association_filters = true。
• 批处理操作：config.batch_actions = true。
• CSV 导出：config.csv_options = { col_sep: ';' }。
• 下载链接：config.download_links = false或[:xml, :pdf]。
• 面包屑：config.breadcrumb = false。
• 敏感属性过滤：config.filter_attributes = [:encrypted_password, :password, :password_confirmation]（默认值见 application_settings.rb）。
• 控制器过滤器：config.before_action :do_something_awesome，会作用于所有 ActiveAdmin 控制器（实现见 application.rb）。

这些配置与本文介绍的所有设置遵循同一套规则：在 setup 块顶层设置即为全局默认值，在config.namespace块内设置则只影响对应命名空间。

• 后端